Importante: O público-alvo deste tópico é a equipa Técnica e de Tecnologia da Informação da sua organização.
Funcionalidade API
A Volunteer Impact API permite que solicite dados de perfil da Volunteer Impact para serem utilizados num programa ou aplicação externos.
Autenticação
A nossa API utiliza a autenticação básica HTTP sobre HTTPS.
Endpoints da API: Fazer a listagem de Utilizadores
Coletivo: https://api.betterimpact.com/v1/enterprise/users/
Organização: https://api.betterimpact.com/v1/organization/users/
Parâmetros:
Nenhum.
Parâmetro | Descrição | Valores Válidos / Predefinições |
| | |
page_size tamanho_página | O número de resultados por página. | 1 a 250 |
page_number número_página | O número de página a recuperar. | 1 a * |
include_ custom_fields incluir_campos_personalizados | Se deve ou não incluir campos personalizados nos resultados. | “verdadeiro” ou “falso” |
include_ qualifications incluir_qualificações | Se deve ou não incluir qualificações nos resultados. | “verdadeiro” ou “falso” |
include_ memberships incluir_adesões | Se deve ou não incluir informações de adesão nos resultados. | “verdadeiro” ou “falso” |
include_ verified_volunteers_ background_check_ results incluir_resultados_verificação de antecedentes_pessoas voluntárias_verificadas | Se deve ou não incluir, nos resultados, a informação relativa à verificação de antecedentes das Pessoas Voluntárias. | “verdadeiro” ou “falso” |
organization_ids documentos_de_identificação_organização | APENAS ENDPOINT COLETIVO. Uma lista separada por vírgulas dos ID da organização para devolver os resultados. Isto irá devolver todos os utilizadores que pertençam a qualquer uma das organizações passadas. | Uma lista separada por vírgulas dos ID válidos da organização (números inteiros) |
modules módulos | Uma lista separada por vírgulas dos membros do módulo que gostaria de devolver. | Pode usar a forma completa, ou curta para os nomes do módulo: |
admin_status estado_administrador | Uma lista separada por vírgulas dos estados de administrador ao qual gostaria de restringir os resultados. | ativo |
client_status estado_cliente | Uma lista separada por vírgulas dos estados do cliente ao qual gostaria de restringir os resultados. | candidato |
donor_status estado_doador | Uma lista separada por vírgulas dos estados do doador ao qual gostaria de restringir os resultados. | perspectiva |
member_status estado_membro | Uma lista separada por vírgulas dos estados dos membros aos quais gostaria de restringir os resultados. | candidato |
volunteer_status estado_pessoa_voluntária | Uma lista separada por vírgulas dos estados das pessoas voluntárias às quais gostaria de restringir. | candidato |
updated_since atualizado_desde | Este parâmetro restringirá os resultados aos perfis que foram alterados desde a data especificada. | As Datas devem estar de acordo com o formato ISO 8601 (usando o seguinte formato da cadeia de caracteres: “yyyy’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffK”). Consulte este documento para obter mais informações: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier. |
Parâmetros de Resposta:
Propriedades | Tipo | Descrição |
| | |
Cabeçalho | Objeto. Veja abaixo as propriedades. | Informações de cabeçalho relacionadas com paginação e conjunto de resultados. |
Utilizadores | Vetor de objetos do utilizador. Ver a secção de Utilizador único para descrições das propriedades. | Uma lista dos utilizadores que correspondem aos parâmetros de pesquisa. |
Propriedades do Cabeçalho:
Propriedades | Tipo | Descrição |
| | |
first_item_on_page primeiro_item_na_página | integer inteiro | O índice que tem como base o nº 1 do primeiro item na página devolvida da coleção de utilizadores. |
has_next_page tem_página_seguinte | boolean booliano | É verdadeiro se houver mais páginas a serem devolvidas. |
has_previous_page tem_página_anterior | booliano | É verdadeiro se já existirem páginas antes da coleção de utilizadores devolvida. |
is_first_page é_primeira_página | booliano | É verdadeiro se a coleção devolvida for da página 1. |
is_last_page é_última_página | booliano | Verdadeiro se a coleção devolvida for da última página. |
last_item_on_page último_item_na_página | inteiro | O índice que tem como base o nº 1 do último item na página devolvida da coleção de utilizadores. |
page_count contagem_de_páginas | inteiro | O número de páginas na coleção de utilizadores. |
page_number número_da_página | inteiro | O número da página devolvida. |
page_size tamanho_da_página | inteiro | O tamanho da página devolvida. |
total_items_count contagem_total_de_itens | inteiro | O número total de utilizadores que correspondem aos parâmetros de pesquisa em todas as páginas. |
Endpoints da API: Utilizador Único
Parâmetros:
Parâmetro | Descrição |
{id_utilizador} | O ID do utilizador que deseja recuperar/obter. |
Parâmetros de pesquisa:
Nenhum.
Resposta:
Um ficheiro de um único utilizador, contendo os seus próprios campos, bem como documentos de adesão, documentos de campos personalizados e documentos de qualificações.
As qualificações só serão incluídas se as suas credenciais de utilizador API tiverem acesso ao módulo Pessoa Voluntária.
Os Campos personalizados só serão incluídos se as suas credenciais de utilizador API tiverem acesso a pelo menos um módulo que esteja indicado no campo personalizado (a ligação entre os seus módulos e os do campo personalizado.).
Propriedades do Utilizador:
Propriedade | Tipo | Descrição/Notas |
user_id id_utilizador | inteiro | ID único do utilizador |
first_name nome | cadeia | Nome |
last_name apelido | cadeia | Apelido |
legal_first_name | cadeia | Primeiro Nome Legal |
middle_name | cadeia | Nome do meio |
title título | cadeia | Título (saudação) |
suffix sufixo | cadeia | Sufixo |
address_line_1 endereço_nº_1 | cadeia | Endereço Nº1 |
address_line_2 endereço_nº_2 | cadeia | Endereço Nº2 |
city cidade | cadeia | Cidade |
zip_code código_postal | cadeia | Código Postal |
state | cadeia | Distrito / Freguesia / Concelho |
country país | cadeia | País |
email_address endereço_de_correio_eletrónico | cadeia | Endereço de correio eletrónico |
secondary_email_address endereço_de_correio_eletrónico_secundário | cadeia | Endereço de correio eletrónico secundário |
mobile_email_address endereço_eletrónico_móvel | cadeia | Endereço de correio eletrónico telemóvel |
home_phone telefone_de _casa | cadeia | Telefone de casa |
work_phone telefone_trabalho | cadeia | Número de telefone trabalho |
work_phone_ext extensão_telefone_trabalho | cadeia | Extensão do número de telefone de trabalho |
cell_phone telemóvel | cadeia | Número de telemóvel |
phone_preference contacto_telefónico_preferencial | cadeia | Contacto telefónico preferencial |
twitter_username utilizador_twitter | cadeia | Nome de utilizador do Twitter |
linkedIn_profile_url url_perfil_linkedin | cadeia | URL do perfil do LinkedIn |
Instagram_username utilizador_instagram | cadeia | Nome de utilizador do Instagram |
username nome de utilizador | cadeia | Nome de utilizador |
birthday data de nascimento | cadeia | Data de nascimento no formato ISO 8601 UTC (pode não ser aplicável) |
date_created data_criada | cadeia | Data em que a conta foi criada, no formato ISO 8601 UTC |
date_updated data_atualizada | cadeia | Data em que a conta foi atualizada pela última vez, no formato ISO 8601 UTC |
region região | cadeia | Nome Localizado da região |
region_code código_região | cadeia | Código postal da região |
is_group é_grupo | booliano | Este perfil representa um grupo? |
group_name nome_grupo | cadeia | Nome do grupo |
photo_url_scaled url_foto_em_escala | cadeia | URL de uma versão reduzida da foto do utilizador |
photo_url_original url_foto_original | cadeia | URL da foto do utilizador original |
timeclock_qr_code_url | cadeia | URL da imagem do QR code do utilizador |
memberships adesões | array of membership objects conjunto de objetos de adesão | Ver abaixo propriedades |
custom_fields campos_personalizáveis | array of custom field objects conjunto de objetos de campos personalizáveis | Ver abaixo propriedades |
qualifications qualificações | array of qualification objects conjunto de objetos de qualificações | Ver abaixo propriedades |
background_check_results resultados_verificação_antecedentes | array of background check objects conjunto de objetos de verificações de antecedentes | Ver abaixo propriedades |
Propriedades de Adesões:
Propriedade | Tipo | Descrição / Notas |
organization_member_id id_membro_organização | inteiro | Identificador único do objeto de adesão |
organization_id id_organização | inteiro | Documento de Identificação da Organização |
organization_name nome_organização | string cadeia | Nome da Organização |
date_created data_criada | cadeia | Data em que a adesão foi criada em formato ISO 8601 UTC |
date_updated data_atualizada | cadeia | Data de adesão foi atualizada em formato ISO 8601 UTC |
is_administrator é_administrador | boolean booliano | Verdadeiro se o utilizador fizer parte do módulo administrador nesta organização |
administrator_status estado_administrador | cadeia | Estado localizado do utilizador no módulo administrador (pode ser nulo) |
administrator_type tipo_administrador | cadeia | Tipo localizado (Completo, Módulo, Limitado) de administrador (pode ser nulo) |
is_client é_cliente | booliano | Verdadeiro se o utilizador fizer parte do módulo cliente nesta organização |
client_status estado_cliente | cadeia | Estado localizado do utilizador no módulo cliente (pode ser nulo) |
client_date_joined data_adesão_cliente | cadeia | Data de adesão como cliente no formato ISO 8601 UTC (pode ser nula) |
client_last_status_change alteração_último_estado_cliente | cadeia | Data da última alteração do estatuto de cliente no formato ISO 8601 UTC (pode ser nula) |
donor_date_joined data_adesão_doador | cadeia | Data de adesão como doador no formato ISO 8601 UTC (pode ser nula) |
Donor_last_status_change última_alteração_estado_doador | cadeia | Data da última alteração do estatuto de doador no formato ISO 8601 UTC (pode ser nula) |
member_date_joined data_adesão_membro | cadeia | Data de adesão como membro no formato ISO 8601 UTC (pode ser nula) |
member_last_status_change última_alteração_estado_membro | cadeia | Data da última alteração do estado do membro no formato ISO 8601 UTC (pode ser nula) |
is_donor é_doador | booliano | Verdadeiro se o utilizador fizer parte do módulo doador é esta organização |
donor_status estado_doador | cadeia | Estado localizado do utilizador no módulo doador (pode ser nulo) |
is_member é_membro | booliano | Verdadeiro que se o utilizador fizer parte do módulo de membros é esta organização |
member_status estado_membro | cadeia | Estado localizado do utilizador no módulo de membros (pode ser nulo) |
is_volunteer é_pessoa_voluntária | booliano | Verdadeiro que se o utilizador fizer parte do módulo de pessoas voluntárias é esta organização |
volunteer_status estado_pessoa voluntária | cadeia | Estado localizado do utilizador no módulo de pessoas voluntárias (pode ser nulo) |
volunteer_inactive_status_reason motivo_estado_inativo_pessoa voluntária | cadeia | Motivo do estado de pessoa voluntária inativo localizado (pode ser nulo) |
volunteer_archived_status_reason motivo_estado_arquivado_pessoa voluntária | cadeia | Motivo do estado de pessoa voluntária arquivado localizado (pode ser nulo) |
volunteer_last_status_change última_alteração_estado_pessoa voluntária | cadeia | Data da última alteração do estado da pessoa voluntária no formato ISO 8601 UTC (pode ser nula) |
volunteer_notes notas_pessoa voluntária | cadeia | Notas da Pessoa Voluntária (pode ser nulo) |
volunteer_application_form formulário_candidatura_pessoa voluntária | inteiro | Número do Formulário de Candidatura a Pessoa Voluntária (pode ser nulo) |
volunteer_date_joined data_adesão_pessoa voluntária | cadeia | Data de adesão como pessoa voluntária no formato ISO 8601 UTC (pode ser nula) |
volunteer_total_hours total_horas_pessoa voluntária | número | Total de horas registadas para pessoas voluntárias |
Propriedades de Campos Personalizáveis:
Propriedade | Tipo | Descrição / Notas |
| | |
type tipo | string / constant cadeia / contante | Tipo de campos personalizáveis: sim_não texto_curto número texto_longo ficheiro drop_down data caixa_de_verificação |
value | sim_não (booliano) | Verdadeiro = sim, Falso = Não |
value_id id_valor | inteiro | Para campos personalizáveis do tipo drop_down apenas (o id do valor selecionado) |
custom_field_id id_campo_personalizável | inteiro | Id do Campo Personalizável |
custom_field_name nome_campo_personalizável | cadeia | Nome do Campo Personalizável |
custom_field_category_id id_categoria_campo_personalizável | inteiro | Id de Categoria de Campo Personalizável (pode ser nulo) |
custom_field_category_name nome_categoria_campo_personalizável | cadeia | Nome de Categoria de Campo Personalizável |
Propriedades de Qualificação:
Propriedade | Tipo | Descrição / Notas |
| | |
qualification_id id_qualificação | inteiro | Id da Qualificação |
qualification_name nome_qualificação | cadeia | Nome da Qualificação |
qualification_expires expira_qualificação | booliano | Verdadeiro se a qualificação é uma qualificação a expirar |
value valor | cadeia | Texto de nível de qualificação selecionado |
value_id id_valor | inteiro | ID do nível de qualificação selecionado |
expiry_date data_validade | cadeia | Data de validade no formato ISO 8601 UTC (pode ser nula) |
Propriedades de Verificação de Antecedentes:
Propriedade | Tipo | Descrição / Notas |
| | |
result_type_id id_tipo_resultado | inteiro | ID do tipo de resultado |
result_type_name nome_tipo_resultado | cadeia | Nome do tipo de resultado |
result_type_expires tipo_resultado_expira | booliano | Verdadeiro se o tipo de resultado for um tipo de resultado expirado |
state estado | cadeia | Verificação do estado atual dos antecedentes desta pessoa |
needs_review_reason necessita_revisão_razão | cadeia | Cadeia que contém a razão pela qual esta pessoa necessita de revisão (em branco se o estado não necessita de revisão) |
effective_date data_efetiva | data | Data em que esta verificação de antecedentes é efetiva em |
expiry_date data_validade | data | Data em que esta verificação de antecedentes expira (nula se não expirar) |
Ficheiros de Campos Personalizáveis
Coletivo: https://api.betterimpact.com/v1/enterprise/users/{user_id}/custom_fields/{user_custom_field_id}/file
Organização: https://api.betterimpact.com/v1/organization/users/{user_id}/custom_fields/{user_custom_field_id}/file
Estes endereços são específicos como o valor do campo personalizado quando os campos personalizados são recuperados como parte de um único ou lista de utilizadores.
Parâmetros:
Parâmetro | Descrição |
| |
{user_id} {id_utilizador} | A identificação do utilizador ao qual pertence o ficheiro de campo personalizável |
{user_custom_field_id} {id_campo_personalizável_utilizador} | O id do valor do campo personalizável do utilizador |
Parâmetros de Pesquisa:
Nenhum.
Resposta:
O arquivo que foi solicitado, como um fluxo de bytes.