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 Predefinição: 100 |
| page_number número_página | O número de página a recuperar. | 1 a * Predefinição: 1 |
| include_ custom_fields incluir_campos_personalizados | Se deve ou não incluir campos personalizados nos resultados. | “verdadeiro” ou “falso” Predefinição: “verdadeiro” |
| include_ qualifications incluir_qualificações | Se deve ou não incluir qualificações nos resultados. | “verdadeiro” ou “falso” Predefinição: “verdadeiro” |
| include_ memberships incluir_adesões | Se deve ou não incluir informações de adesão nos resultados. | “verdadeiro” ou “falso” Predefinição: “verdadeiro” |
| 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” Predefinição: “verdadeiro” |
| 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) Predefinição: Todas as organizações do coletivo. |
| 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: pessoa voluntária / vol cliente / cli membro / mem doador / don administrador / admin Predefinição: Todos os módulos. Quando deixados de fora, os módulos serão inferidos por quaisquer parâmetros específicos {modulo}_estado. |
| admin_status estado_administrador | Uma lista separada por vírgulas dos estados de administrador ao qual gostaria de restringir os resultados. | ativo inativo Predefinição: Todos os estados. |
| client_status estado_cliente | Uma lista separada por vírgulas dos estados do cliente ao qual gostaria de restringir os resultados. | candidato em processo / em_processo aceite inativo arquivado Predefinição: Todos os estados. |
| donor_status estado_doador | Uma lista separada por vírgulas dos estados do doador ao qual gostaria de restringir os resultados. | perspectiva ativo inativo arquivado Predefinição: Todos os estados. |
| member_status estado_membro | Uma lista separada por vírgulas dos estados dos membros aos quais gostaria de restringir os resultados. | candidato em processo / em_processo aceite inativo arquivado Predefinição: Todos os estados. |
| volunteer_status estado_pessoa_voluntária | Uma lista separada por vírgulas dos estados das pessoas voluntárias às quais gostaria de restringir. Pode usar “arquivado” para incluir todos os subtipos arquivados e “inativo” para incluir todos os subtipos inativos. | candidato em processo aceite inativoacurtoprazo (ou: inativo_a_curto_prazo) inativoalongoprazo (ou: inativo_a_longo_prazo) arquivadonãoiniciou (ou: arquivado_não_iniciou) arquivadorejeitado (ou: arquivado_rejeitado) arquivadodispensado (ou: arquivado_dispensado) arquivadodeslocado (ou: arquivado_deslocado) arquivadodesistiu (ou: arquivado_desistiu) arquivadofaleceu (ou: arquivado_faleceu) arquivadooutro (ou: arquivado_outro) Predefinição: Todos os estados. |
| 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. Predefinição: Vazio. Irá devolver todos os perfis, independentemente da sua última atualização. |
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
Coletivo: https://api.betterimpact.com/v1/enterprise/users/{user_id}
Organização: https://api.betterimpact.com/v1/organization/users/{user_id}
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 (varies based on type property) valor (varia baseado no tipo de propriedade) | sim_não (booliano) texto_curto (cadeia) número (número) texto_longo (cadeia) ficheiro (cadeia) drop_down (cadeia) data (cadeia) | Verdadeiro = sim, Falso = Não cadeia pode ser um decimal string URL do recurso do ficheiro na API Texto do valor selecionado Data no formato ISO 8601 UTC |
| 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.