Contatos

Contatos são uma parte central do seven. Nesta página, vamos explorar os diferentes endpoints de contato que permitem gerenciar contatos programaticamente. Vamos ver como consultar, criar, atualizar e excluir contatos.

O Modelo de Contato

O modelo de contato contém todas as informações sobre seus contatos, como nome, avatar e número de telefone. Caso você tenha criado propriedades de contato personalizadas, cada nome único será exibido como uma propriedade adicional no objeto properties.

Propriedades

  • Name
    id
    Type
    integer
    Description

    ID única do contato.

  • Name
    avatar
    Type
    string
    Description

    A URL do avatar do contato.

  • intials
      • Name
        initials
        Type
        string
        Description

        As iniciais do contato.

      • Name
        color
        Type
        hex color
        Description

        Código de cor hexadecimal.

  • validation
      • Name
        state
        Type
        string
        Description

        O último resultado de validação do número de celular do contato. Pode ter um dos valores valid, invalid, absent ou unknown.

      • Name
        timestamp
        Type
        timestamp
        Description

        O momento da última validação do número de celular do contato.

  • properties
    • Name
      firstname
      Type
      string
      Description

      Primeiro nome do contato.

    • Name
      lastname
      Type
      string
      Description

      Sobrenome do contato.

    • Name
      home_number
      Type
      phonenumber
      Description

      Número de telefone fixo do contato.

    • Name
      mobile_number
      Type
      phonenumber
      Description

      Número de celular do contato.

    • Name
      address
      Type
      string
      Description

      Endereço do contato.

    • Name
      email
      Type
      string
      Description

      E-mail do contato.

    • Name
      postal_code
      Type
      integer
      Description

      Código postal do contato.

    • Name
      city
      Type
      string
      Description

      Cidade do contato.

    • Name
      birthday
      Type
      date
      Description

      Data de nascimento do contato.

    • Name
      notes
      Type
      string
      Description

      Notas sobre o contato.

  • Name
    groups
    Type
    array
    Description

    Um array consistindo dos IDs dos grupos nos quais o contato é membro. Ao alterar ou criar um contato, se esta propriedade for especificada, deve conter todos os IDs dos grupos nos quais o contato deve ser membro.

  • Name
    created
    Type
    timestamp
    Description

    Momento da criação do contato.

{
    "id": 12876881,
    "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
    "validation": {
        "state": "absent",
        "timestamp": "2024-01-09 16:08:29"
    },
    "initials": {
        "initials": "PM",
        "color": "9EB384"
    },
    "properties": {
        "firstname": "Peter",
        "lastname": "Mustermann",
        "mobile_number": 4917612345678,
        "home_number": null,
        "email": null,
        "address": null,
        "postal_code": null,
        "city": null,
        "birthday": "1977-07-07",
        "notes": null,
    },
    "groups": [
        18008
    ],
    "created": "2024-01-09 13:14:48"
}
GET/api/contacts

Consultar lista de contatos

Com este endpoint, você pode obter uma lista paginada de todos os seus contatos. Por padrão, são exibidos no máximo 30 contatos por página.

  • Name
    order_by
    Type
    string
    Optional
    Optional
    Description

    A coluna pela qual os contatos devem ser ordenados.

  • Name
    order_direction
    Type
    string
    Optional
    Optional
    Description

    A direção da ordenação. Pode ser asc ou desc.

  • Name
    search
    Type
    string
    Optional
    Optional
    Description

    Com este parâmetro, você pode pesquisar em seus contatos em todas as colunas.

  • Name
    offset
    Type
    integer
    Optional
    Optional
    Description

    A página que deve ser exibida.

  • Name
    limit
    Type
    integer
    Optional
    Optional
    Description

    O número de contatos que deve ser exibido por página. Pode ser um valor entre 30 e 500.

  • Name
    group_id
    Type
    integer
    Optional
    Optional
    Description

    Exiba apenas contatos que são membros de um determinado grupo.

Anfrage

GET
/api/contacts
curl -G https://gateway.seven.io/api/contacts \
    -H "X-Api-Key: SUA_CHAVE_API" \

Antwort

{
    "pagingMetadata": {
        "offset": 0,
        "count": 30,
        "total": 20013,
        "limit": 30,
        "has_more": true
    },
    "data": [
        {
            "id": 12876881,
            "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
            "validation": {
                "state": "absent",
                "timestamp": "2024-01-09 16:08:29"
            },
            "initials": {
                "initials": "PM",
                "color": "9EB384"
            },
            "properties": {
                "firstname": "Peter",
                "lastname": "Mustermann",
                "mobile_number": 4917612345678,
                "home_number": null,
                "email": null,
                "address": null,
                "postal_code": null,
                "city": null,
                "birthday": "1977-07-07",
                "notes": null,
            },
            "groups": [
                18008
            ],
            "created": "2024-01-09 13:14:48"
        },
        {
            "id": 12454415,
            // ...
        }
    ]
}
POST/api/contacts

Criar contato

Com este endpoint, você pode adicionar um novo contato. Se tudo der certo, você receberá o objeto de contato criado como resposta. Caso você tenha criado propriedades de contato personalizadas e deseje defini-las no contato, por favor, forneça o nome exclusivo da propriedade como um parâmetro adicional.

cURL

POST
/api/contacts
curl https://gateway.seven.io/api/contacts \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -d "firstname=Frank" \
    -d "lastname=McAllister" \
    -d "mobile_number=1-800-759-3000" \
    -d "avatar=https://picsum.photos/200"

Response

{
    "id": 12876882,
    "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
    "validation": {
        "state": null,
        "timestamp": null
    },
    "initials": {
        "initials": "FM",
        "color": "EEE0C9"
    },
    "properties": {
        "firstname": "Frank",
        "lastname": "McAllister",
        "mobile_number": "18007593000",
        "home_number": null,
        "email": null,
        "address": null,
        "postal_code": null,
        "city": null,
        "birthday": null,
        "notes": null,
    },
    "groups": [],
    "created": "2024-01-09 13:12:48"
}
GET/api/contacts/:id

Obter contato

Este endpoint permite que você obtenha um contato especificando seu ID. Na lista acima nesta página, você pode verificar quais propriedades estão incluídas nos objetos de contato.

cURL

GET
/api/contacts/12876881
curl https://gateway.seven.io/api/contacts/12876881 \
    -H "X-Api-Key: SUA_CHAVE_API"

Response

{
    "id": 12876881,
    "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
    "validation": {
        "state": "absent",
        "timestamp": "2024-01-09 16:08:29"
    },
    "initials": {
        "initials": "PM",
        "color": "9EB384"
    },
    "properties": {
        "firstname": "Peter",
        "lastname": "Mustermann",
        "mobile_number": 4917612345678,
        "home_number": null,
        "email": null,
        "address": null,
        "postal_code": null,
        "city": null,
        "birthday": "1977-07-07",
        "notes": null,
    },
    "groups": [
        18008
    ],
    "created": "2024-01-09 13:14:48"
}
PATCH/api/contacts/:id

Atualizar contato

Este endpoint permite que você altere uma ou mais propriedades de um contato. Os nomes das propriedades podem ser encontrados na lista do modelo de contato. Como resposta, você receberá o objeto de contato atualizado.

cURL

PATCH
/api/contacts/12876881
curl -X PATCH https://gateway.seven.io/api/contacts/12876881 \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -d firstname="Marc" \
    -d lastname="Gump"

Response

{
    "id": 12876881,
    "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
    "validation": {
        "state": "absent",
        "timestamp": "2024-01-09 16:08:29"
    },
    "initials": {
        "initials": "CF",
        "color": "9EB384"
    },
    "properties": {
        "firstname": "Marc",
        "lastname": "Gump",
        "mobile_number": 4917612345678,
        "home_number": null,
        "email": null,
        "address": null,
        "postal_code": null,
        "city": null,
        "birthday": "1977-07-07",
        "notes": null
    },
    "groups": [
    ´   18008
    ],
    "created": "2024-01-09 13:14:48"
}
DELETE/api/contacts/:id

Excluir contato

Este endpoint permite que você exclua contatos da sua lista de contatos.

cURL

DELETE
/api/contacts/12454414
curl -X DELETE https://gateway.seven.io/api/contacts/12454414 \
    -H "X-Api-Key: SUA_CHAVE_API"