Create a contact

Adds a contact to an address book.

POST /v1/contacts

Permission

The key must be granted contacts.write

A key without it gets 403 insufficient_scope, with the missing permission named in details.

Request body

name is the only required field. Omitted fields are simply absent on the contact.

Field	Type	Description
`name` required	string	The display name. Required when creating.
`address_book_id`	string	Which book to file it in. Defaults to the mailbox's own book.
`given_name`	string
`family_name`	string
`emails`	object[]	Replaces the whole list. Its fields are below.
`phones`	object[]	Replaces the whole list. Its fields are below.
`organization`	string
`title`	string
`notes`	string

Each item in emails

Field	Type	Description
`address` required	string
`type`	string

Each item in phones

Field	Type	Description
`number` required	string
`type`	string

Request

curl https://api.veruapis.com/v1/contacts \
  -X POST \
  -H "Authorization: Bearer vak_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "address_book_id": "01918e4b-2002-7f11-b4a9-0242ac130003",
  "name": "Bob Smith",
  "given_name": "Bob",
  "family_name": "Smith",
  "emails": [ { "address": "[email protected]", "type": "work" } ],
  "organization": "Example Ltd"
}'

Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.

Response

Answers 201.

Field	Type	Description
`id`	string
`address_book_id`	string	Which book holds it.
`name`	string	The display name. Core calls this formatted_name; it is name here, because that is what every other resource in this API calls the human-readable string.
`given_name`	string
`family_name`	string
`emails`	object[]	Addresses, in stored order. The first is the one to compose to. Its fields are below.
`phones`	object[]	Numbers, in stored order. Its fields are below.
`organization`	string
`title`	string	Their job title, not a name prefix.
`notes`	string
`created_at`	RFC 3339
`updated_at`	RFC 3339

Each item in emails

Field	Type	Description
`address` required	string
`type`	string	A label such as work or home. Free text, not a closed set.

Each item in phones

Field	Type	Description
`number` required	string
`type`	string	A label such as cell or work.

{
  "data": {
  "id": "01918e4b-2101-7f11-b4a9-0242ac130003",
  "address_book_id": "01918e4b-2002-7f11-b4a9-0242ac130003",
  "name": "Bob Smith",
  "emails": [ { "address": "[email protected]", "type": "work" } ],
  "organization": "Example Ltd",
  "created_at": "2026-05-20T12:00:00Z",
  "updated_at": "2026-05-20T12:00:00Z"
},
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}

Worth knowing

name is the only required field. A field this API does not publish is refused rather than forwarded, so a typo in a key is a 400 here instead of a silently dropped value upstream.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

POST `/v1/contacts`

Your API key Used once, never stored.

address_book_id name given_name family_name emails organization

Create a contact

Permission

Request body

Each item in emails

Each item in phones

Request

Response

Each item in emails

Each item in phones

Related