Contacts & Accounts

Handle ImBox contacts and accounts. A contact can be connected to an account with the accountId property.

Create contact

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user

Body

Name	Type	Description
accountId	Integer \| null	Adds this contact to an existing account.
description	String \| null	Max 500 characters.
externalId	String \| null	Max 50 characters.
externalUrl	String \| null	Max 250 characters.
firstName	String \| null	You must provide at least one of `firstName` or `lastName`. Max 50 characters.
lastName	String \| null	You must provide at least one of `firstName` or `lastName`. Max 50 characters.
fullName	String \| null	If not provided, it is constructed from `firstName` and `lastName`. Max 100 characters.
title	String \| null	Max 50 characters.
addresses	Array<{ address: String, isPrimary: Boolean }> \| null	Only the first address marked `isPrimary` is kept, and if none is marked, the first entry becomes primary. Max 200 characters.
emails	Array<{ email: String, isPrimary: Boolean }> \| null	Only the first email marked `isPrimary` is kept, and if none is marked, the first entry becomes primary. Max 250 characters
phones	Array<{ phone: String, isPrimary: Boolean }> \| null	Must be in E.164 format. Only the first phone marked `isPrimary` is kept, and if none is marked, the first entry becomes primary.
labels	Array<String> \| null	Labels to attach to the contact. Case sensitive. If the label does not exist it will not be addded to the contact.

Usage

curl -X POST -H "Content-Type: application/json" -d @contact.json "https://apiv2.imbox.io/api/:apiKey/:userId/contacts"

contact.json

{
  "firstName": "Arne",
  "lastName": "Andersson",
  "title": "CEO",
  "description": "This is a contact description",
  "emails": [{ "email": "arne@example.com", "isPrimary": true }],
  "phones": [{ "phone": "+46762004545", "isPrimary": true }],
  "externalUrl": "http://example.com/abc/123",
  "externalId": "123",
  "accountId": 45
}

Response

200 OK

{
  "id": 100,
  "userId": 200,
  "crmId": 1,
  "accountId": 45,
  "externalId": "123",
  "externalUrl": "http://example.com/abc/123",
  "firstName": "Arne",
  "lastName": "Andersson",
  "fullName": "Arne Andersson",
  "title": "CEO",
  "picture": null,
  "activityAt": "2020-01-01T13:00:00.000Z",
  "createdAt": "2020-01-01T13:00:00.000Z",
  "description": "This is a contact description",
  "addresses": [],
  "emails": [{ "email": "arne@example.com", "isPrimary": true }],
  "phones": [{ "phone": "+46762004545", "isPrimary": true }],
  "labels": []
}

400 Bad Request

{
  "message": "Validation",
  "errors": [
    {
      "value": "", // The invalid value you provided
      "index": 0, // The index of the invalid item, if it's in an array
      "label": "firstName" // The name of the invalid property
    },
    {
      "value": "example.com",
      "index": 1,
      "label": "emails"
    }
  ]
}

{
  "message": "accountId not found",
  "errors": []
}

409 Conflict

{
  "message": "Conflict",
  "error": {
    "field": "email",
    "row": {
      "email": "name@example.com",
      "isPrimary": true
    }
  }
}

{
  "message": "Conflict",
  "error": {
    "field": "phone",
    "row": {
      "phone": "+46701740635",
      "isPrimary": true
    }
  }
}

{
  "message": "Conflict",
  "error": {
    "field": "unknown",
  }
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Write

Update contact

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user
id*	Integer	Id of the contact

Body

Name	Type	Description
accountId	Integer \| null	Add this contact to an existing account. Send `null` to remove the contact from its current account.
description	String \| null	Max 500 characters.
externalId	String \| null	Max 50 characters.
externalUrl	String \| null	Max 250 characters.
firstName	String \| null	Max 50 characters.
lastName	String \| null	Max 50 characters.
fullName	String \| null	If not provided, it is reconstructed from `firstName` and `lastName`, using the current values if not included in the request. Max 100 characters.
title	String \| null	Max 50 characters.
addresses	Array<{ address: String, isPrimary: Boolean }> \| null	Replaces all existing addresses. Only the address first marked `isPrimary` is kept, and if none is marked, the first entry becomes primary. Max 200 characters.
emails	Array<{ email: String, isPrimary: Boolean }> \| null	Replaces all existing emails. Only the first email marked `isPrimary` is kept, and if none is marked, the first entry becomes primary. Max 250 characters.
phones	Array<{ phone: String, isPrimary: Boolean }> \| null	Replaces all existing phones. Must be in E.164 format. Only the first phone marked `isPrimary` is kept, and if none is marked, the first entry becomes primary.
labels	Array<String> \| null	Replaces all labels on the contact. Case sensitive. If the label does not exist it will not be added to the contact.

Usage

curl -X PUT -H "Content-Type: application/json" -d @contact.json "https://apiv2.imbox.io/api/:apiKey/:userId/contacts/:id"

contact.json

{
  "firstName": "Bosse",
  "emails": [{ "email": "bosse@example.com", "isPrimary": true }],
  "description": "Moved from old account",
  "externalId": "456",
  "externalUrl": "http://example.com/efg/456",
  "accountId": 46
}

Response

200 OK

{}

400 Bad Request

{
  "message": "Validation",
  "errors": [
    {
      "value": "", // The invalid value you provided
      "index": 0, // The index of the invalid item, if it's in an array
      "label": "firstName" // The name of the invalid property
    },
    {
      "value": "example.com",
      "index": 1,
      "label": "emails"
    }
  ]
}

{
  "message": "accountId not found",
  "errors": []
}

409 Conflict

{
  "message": "Conflict",
  "error": {
    "field": "email",
    "row": {
      "email": "name@example.com",
      "isPrimary": true
    }
  }
}

{
  "message": "Conflict",
  "error": {
    "field": "phone",
    "row": {
      "phone": "+46701740635",
      "isPrimary": true
    }
  }
}

{
  "message": "Conflict",
  "error": {
    "field": "unknown",
  }
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Write

Delete contact

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user
id*	Integer	Id of the contact

Usage

curl -X DELETE "https://apiv2.imbox.io/api/:apiKey/:userId/contacts/:id"

Response

200 OK

{}

404 Not Found

{
  "code": "NotFound",
  "message": "Not Found"
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Write

Get contacts

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user

Query parameters

Name	Type	Description
id	Integer	Id of contact
email	String	Email address of contact
phone	String	Phone number of contact in E.164 format
limit	Integer	Number of contacts to return. Default: 50. Max: 100
after	Integer	Cursor for next result set by id

Usage

curl -X GET "https://apiv2.imbox.io/api/:apiKey/:userId/contacts?limit=2"

Response

200 OK

{
    "contacts": [
        {
            "id": 100,
            "userId": 200,
            "accountId": null,
            "crmId": 1,
            "description": null,
            "externalId": null,
            "externalUrl": null,
            "firstName": "Arne",
            "lastName": "Andersson",
            "fullName": "Arne Andersson",
            "picture": null,
            "title": "CEO",
            "activityAt": "2020-01-01T13:00:00.000Z",
            "modifiedAt": null,
            "createdAt": "2020-01-01T13:00:00.000Z",
            "updatedAt": null
        },
        {
            "id": 120,
            "userId": 200,
            "accountId": null,
            "crmId": 1,
            "description": null,
            "externalId": null,
            "externalUrl": null,
            "firstName": "Bosse",
            "lastName": "Bengtsson",
            "fullName": "Bosse Bengtsson",
            "picture": null,
            "title": "HR manager",
            "activityAt": "2020-01-01T13:00:00.000Z",
            "modifiedAt": null,
            "createdAt": "2020-01-01T13:00:00.000Z",
            "updatedAt": null
        }
    ]
    "paging": {
        "cursor": {
            "after": 120
        }
    },
    "next": "https://apiv2.imbox.io/api/apiKey/userId/contacts?limit=2&after=120"
}

paging.cursor.after and next are only provided if there are more results than those that were returned.

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Read

Create contact note

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user

Usage

curl -X POST -H "Content-Type: application/json" -d @note.json "https://apiv2.imbox.io/api/:apiKey/:userId/contactNotes"

note.json

{
  "contactId": 1234,
  "content": "A note..."
}

Response

{
  "id": 100
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Write

Delete contact note

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user
id*	Integer	The contact note id

Usage

curl -X DELETE "https://apiv2.imbox.io/api/:apiKey/:userId/contactNotes/:id"

Response

200 OK

{}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Write

Get contact notes

Get notes

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user

Query parameters

Name	Type	Description
contactId	Integer	Contact to filter by
limit	Integer	Number of contacts to return
after	Integer	Cursor for next result set by id

Usage

curl "https://apiv2.imbox.io/api/:apiKey/:userId/contactNotes?contactId=1&limit=2"

Response

200 OK

{
  "notes": [
    {
      "id": 1,
      "contactId": 1,
      "content": "A note...",
      "createdAt": "2020-01-01T13:00:00.000Z"
    },
    {
      "id": 2,
      "contactId": 1,
      "content": "Anoter note...",
      "createdAt": "2020-01-01T13:00:00.000Z"
    }
  ],
  "paging": {
    "cursors": {
      "after": 2
    },
    "next": "https://apiv2.imbox.io/api/apiKey/userId/contactNotes?contactId=1&limit=2&after=2"
  }
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Read

Get contact note

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user
id*	Integer	Note id

Usage

curl "https://apiv2.imbox.io/api/:apiKey/:userId/contactNotes/:id"

Response

200 OK

{
  "id": 1,
  "contactId": 1,
  "content": "A note...",
  "createdAt": "2020-01-01T13:00:00.000Z"
}

204 No Content

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Read

Create account

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user

Body

Name	Type	Description
name*	String	Min 2 characters. Max 50 characters.
description	String \| null
externalId	String \| null	Max 50 characters.
externalUrl	String \| null	Max 250 characters.
labels	Array<String> \| null	Replaces all labels on the account. Case sensitive. If the label does not exist it will not be added to the account.

Usage

curl -X POST -H "Content-Type: application/json" -d @account.json "https://apiv2.imbox.io/api/:apiKey/:userId/accounts"

account.json

{
  "name": "ImBox Sweden AB",
  "externalId": "1234", // optional
  "externalUrl": "https://example.com/1234" // optional
}

Response

200 OK

{
  "id": 100,
  "userId": 1,
  "crmId": 1,
  "externalId": "1234",
  "externalUrl": "https://example.com/1234",
  "name": "ImBox Sweden AB",
  "description": null,
  "labels": []
}

400 Bad Request

{
  "code": "BadRequest",
  "message": "Bad Request"
}

409 Conflict

{
  "message": "Conflict",
  "error": {
    "field": "externalId"
  }
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Write

Update account

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Unique id for the user
id*	Integer	Account id

Body

Name	Type	Description
name	String \| null	Min 2 characters. Max 50 characters.
description	String \| null
externalId	String \| null	Max 50 characters.
externalUrl	String \| null	Max 250 characters.
labels	Array<String> \| null	Replaces all labels on the account. Case sensitive. If the label does not exist it will not be added to the account.

Usage

curl -X PUT -H "Content-Type: application/json" -d @account.json "https://apiv2.imbox.io/api/:apiKey/:userId/accounts/:id"

account.json

{
  "name": "ImBox England Ltd"
}

Response

200 OK

{}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Write

Delete account

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	Integer	Unique id for the user
id*	Integer	Account id

Usage

curl -X DELETE "https://apiv2.imbox.io/api/:apiKey/:userId/accounts/:id"

Response

200 OK

{}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Write

Get accounts

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	Integer	Unique id for the user

Query parameters

Name	Type	Description
limit	Integer	Number of accounts to return
afterId	Integer	Cursor for next result set by id

Usage

curl "https://apiv2.imbox.io/api/:apiKey/:userId/accounts?limit=2"

Response

200 OK

{
  "accounts": [
    {
      "id": 1,
      "userId": 1,
      "crmId": 1,
      "externalId": null,
      "externalUrl": null,
      "name": "ImBox Sweden AB",
      "description": "",
      "createdAt": "2020-01-01T13:00:00.000Z",
      "updatedAt": null,
      "labels": []
    },
    {
      "id": 10,
      "userId": 1,
      "crmId": 1,
      "externalId": "1234",
      "externalUrl": null,
      "name": "ImBox Finland",
      "description": null,
      "createdAt": "2020-01-01T14:00:00.000Z",
      "updatedAt": "2020-01-01T15:00:00.000Z",
      "labels": []
    }
  ],
  "paging": {
    "cursors": {
      "afterId": 10
    },
    "next": "https://apiv2.imbox.io/api/apiKey/userId/accounts?limit=2&afterId=10"
  }
}

paging.cursor.after and next are only provided if there are more results than those that were returned.

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Read

Get account

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	Integer	Unique id for the user
id*	Integer	Account id

Usage

curl "https://apiv2.imbox.io/api/:apiKey/:userId/accounts/:id"

Response

200 OK

{
  "id": 1,
  "userId": 1,
  "crmId": 1,
  "externalId": null,
  "externalUrl": null,
  "name": "ImBox Sweden AB",
  "description": null,
  "createdAt": "2020-01-01T13:00:00.000Z",
  "updatedAt": null,
  "labels": []
}

204 No Content

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Contacts	Read

Create contact​

Parameters​

Body​

Usage​

contact.json​

Response​

200 OK​

400 Bad Request​

409 Conflict​

API key scope access​

Update contact​

Parameters​

Body​

Usage​

contact.json​

Response​

200 OK​

400 Bad Request​

409 Conflict​

API key scope access​

Delete contact​

Parameters​

Usage​

Response​

200 OK​

404 Not Found​

API key scope access​

Get contacts​

Parameters​

Query parameters​

Usage​

Response​

200 OK​

API key scope access​

Create contact note​

Parameters​

Usage​

note.json​

Response​

API key scope access​

Delete contact note​

Parameters​

Usage​

Response​

200 OK​

API key scope access​

Get contact notes​

Parameters​

Query parameters​

Usage​

Response​

200 OK​

API key scope access​

Get contact note​

Parameters​

Usage​

Response​

200 OK​

204 No Content​

API key scope access​

Create account​

Parameters​

Body​

Usage​

account.json​

Response​

200 OK​

400 Bad Request​

409 Conflict​

API key scope access​

Update account​

Parameters​

Body​

Usage​

account.json​

Response​

200 OK​

API key scope access​

Delete account​

Parameters​

Create contact

Parameters

Body

Usage

contact.json

Response

200 OK

400 Bad Request

409 Conflict

API key scope access

Update contact

Parameters

Body

Usage

contact.json

Response

200 OK

400 Bad Request

409 Conflict

API key scope access

Delete contact

Parameters

Usage

Response

200 OK

404 Not Found

API key scope access

Get contacts

Parameters

Query parameters

Usage

Response

200 OK

API key scope access

Create contact note

Parameters

Usage

note.json

Response

API key scope access

Delete contact note

Parameters

Usage

Response

200 OK

API key scope access

Get contact notes

Parameters

Query parameters

Usage

Response

200 OK

API key scope access

Get contact note

Parameters

Usage

Response

200 OK

204 No Content

API key scope access

Create account

Parameters

Body

Usage

account.json

Response

200 OK

400 Bad Request

409 Conflict

API key scope access

Update account

Parameters

Body

Usage

account.json

Response

200 OK

API key scope access

Delete account

Parameters