Contacts

Contacts are a central part of seven. On this page, we'll look at the different contact endpoints you can use to manage contacts programmatically. We'll look at how you can query, create, update and delete contacts.

The contact model

The contact model contains all the information about your contacts, such as their name, avatar and phone number. If you have created your own contact properties, the unique name is output as an additional property in the properties object.

Properties

Name
id
Type
integer
Description
Unique ID of the contact.
Name
avatar
Type
string
Description
The avatar URL of the contact.
intials
validation
properties
- Name
  firstname
  Type
  string
  Description
  First name of the contact.
- Name
  lastname
  Type
  string
  Description
  Last name of the contact.
- Name
  home_number
  Type
  phonenumber
  Description
  Landline number of the contact.
- Name
  mobile_number
  Type
  phonenumber
  Description
  Mobile phone number of the contact.
- Name
  address
  Type
  string
  Description
  Address of the contact.
- Name
  email
  Type
  string
  Description
  E-mail of the contact.
- Name
  postal_code
  Type
  integer
  Description
  Postal code of the contact.
- Name
  city
  Type
  string
  Description
  City of the contact.
- Name
  birthday
  Type
  date
  Description
  Date of birth of the contact.
- Name
  notes
  Type
  string
  Description
  Notes on the contact.
Name
groups
Type
array
Description
An array consisting of the IDs of the groups in which the contact is a member. If this property is specified when changing or creating a contact, it must contain all group IDs in which the contact is to be a member.
Name
created
Type
timestamp
Description
Time at which the contact was created.

{
  "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

Query contact list

You can use this endpoint to retrieve a page-by-page list of all your contacts. By default, a maximum of 30 contacts are displayed per page.

Name
order_by
Type
string
Optional
Optional
Description
The column by which the contacts should be sorted.
Name
order_direction
Type
string
Optional
Optional
Description
The direction of the sorting. Can be either asc or desc.
Name
search
Type
string
Optional
Optional
Description
You can use this parameter to search in all columns in your contacts.
Name
offset
Type
integer
Optional
Optional
Description
The page to be displayed.
Name
limit
Type
integer
Optional
Optional
Description
The number of contacts to be displayed per page. Can be a value between 30 and 500.
Name
group_id
Type
integer
Optional
Optional
Description
Only display contacts who are members of a specific group.

request

GET

/api/contacts

curl -G https://gateway.seven.io/api/contacts \
  -H "X-Api key: YOUR_API_KEY" \

Answer

{
  "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

Create contact

You can use this endpoint to add a new contact. If everything went well, you will receive the created contact object as a response. If you have created your own contact properties and would like to specify these for the contact, please enter the unique name of the property as an additional parameter.

cURL

POST

/api/contacts

curl https://gateway.seven.io/api/contacts \
  -H "X-Api key: YOUR_API_KEY" \
  -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

Retrieve contact

You can use this endpoint to retrieve a contact by specifying its ID. In the list at the top of this page, you can read which properties are contained in contact objects.

cURL

GET

/api/contacts/12876881

curl https://gateway.seven.io/api/contacts/12876881 \
  -H "X-Api key: YOUR_API_KEY"

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

Update contact

You can use this endpoint to change one or more properties of a contact. The names of the properties can be found in the list of the contact model. You will receive the updated contact object in response.

cURL

PATCH

/api/contacts/12876881

curl -X PATCH https://gateway.seven.io/api/contacts/12876881 \
  -H "X-Api key: YOUR_API_KEY" \
  -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

Delete contact

This endpoint allows you to delete contacts from your contact list.

cURL

DELETE

/api/contacts/12454414

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