Contacts API | Genaya API Reference

Core

Contacts

Lightweight contacts used across messaging and call surfaces.

GET/contacts

List contacts

Returns a cursor-paginated list of contacts. Contacts are a per-user private address book, so a key only ever sees the contacts created by its own issuing member, never the whole organization's. Soft-deleted contacts are excluded. Requires scope: contacts:read.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/contacts \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "ct_8fJ2kLqWxr",
      "object": "contact",
      "name": "Jane Doe",
      "phone": "+14155551234",
      "email": "jane@example.com",
      "company": "Acme Clinic",
      "avatarUrl": "",
      "entity": "callCenter",
      "address": {
        "address": "123 Market St",
        "unit": "Suite 200",
        "city": "San Francisco",
        "state": "CA",
        "zipCode": "94103",
        "country": "USA",
        "lat": 37.7793,
        "lng": -122.4193,
        "fullAddress": "123 Market St Suite 200, San Francisco, CA, 94103, USA"
      },
      "notes": [
        {
          "id": "nt_1",
          "text": "Prefers afternoon callbacks.",
          "createdBy": "usr_abc123",
          "createdByName": "Alex Operator",
          "createdAt": "2026-06-17T15:04:05.000Z"
        }
      ],
      "createdAt": "2026-06-17T15:00:00.000Z",
      "updatedAt": "2026-06-17T15:04:05.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/contacts

Create a contact

Creates a new contact. At least one of name or phone must be provided. The address fullAddress field is always recomputed server-side from the address parts. Supports idempotent retries via the Idempotency-Key header. Requires scope: contacts:write.

Request body

FieldTypeDescription

name

string

Display name. Max 120 characters.

phone

string

Primary phone number. Max 32 characters.

email

string

Email address. Max 120 characters.

company

string

Company or organization name. Max 120 characters.

avatarUrl

string

URL of the contact's avatar image. Max 600 characters.

entity

enumchats | rooms | callCenter | both

Which surface(s) this contact belongs to. Any unrecognized value normalizes to "both".

address

object

Address parts supplied on write. fullAddress is ignored on input and always recomputed server-side from these parts.

address

string

Street address line. Max 240 characters.

unit

string

Unit, suite, or apartment. Max 60 characters.

city

string

Max 120 characters.

state

string

Max 120 characters.

zipCode

string

Postal code. Max 20 characters. The alias "zip" is also accepted.

country

string

Max 120 characters.

lat

number

Latitude. Stored as null when not a finite number.nullable

lng

number

Longitude. Stored as null when not a finite number.nullable

Response 201

FieldTypeDescription

id

string

Unique identifier of the contact.

object

string

The object type. Always "contact".

name

string

Display name of the contact. Empty string when unset.

phone

string

Primary phone number. Empty string when unset.

email

string

Email address. Empty string when unset.

company

string

Company or organization name for the contact. Empty string when unset.

avatarUrl

string

URL of the contact's avatar image. Empty string when unset.

entity

enumchats | rooms | callCenter | both

Which surface(s) this contact belongs to. Any unrecognized or missing value normalizes to "both".

address

object

Structured address for a contact. fullAddress is read-only and recomputed server-side from the parts on every write.

address

string

Street address line.

unit

string

Unit, suite, or apartment.

city

string

state

string

zipCode

string

country

string

lat

number

Latitude, or null when unset.nullable

lng

number

Longitude, or null when unset.nullable

fullAddress

string

Server-computed single-line address. Read-only.

notes

array of object

Embedded notes attached to the contact.

id

string

text

string

createdBy

string

Identifier of the member who created the note.nullable

createdByName

string

Display name of the member who created the note.nullable

createdAt

string <date-time>

ISO-8601 timestamp when the note was created.nullable

createdAt

string <date-time>

ISO-8601 timestamp when the contact was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp when the contact was last updated.nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

409Idempotency-Key reused with a different body

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X POST https://api.genaya.com/v1/contacts \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Jane Doe",
  "phone": "+14155551234",
  "email": "jane@example.com",
  "company": "Acme Clinic",
  "entity": "callCenter",
  "address": {
    "address": "123 Market St",
    "unit": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94103",
    "country": "USA",
    "lat": 37.7793,
    "lng": -122.4193
  }
}'

Example response

{
  "data": {
    "id": "ct_8fJ2kLqWxr",
    "object": "contact",
    "name": "Jane Doe",
    "phone": "+14155551234",
    "email": "jane@example.com",
    "company": "Acme Clinic",
    "avatarUrl": "",
    "entity": "callCenter",
    "address": {
      "address": "123 Market St",
      "unit": "Suite 200",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94103",
      "country": "USA",
      "lat": 37.7793,
      "lng": -122.4193,
      "fullAddress": "123 Market St Suite 200, San Francisco, CA, 94103, USA"
    },
    "notes": [
      {
        "id": "nt_1",
        "text": "Prefers afternoon callbacks.",
        "createdBy": "usr_abc123",
        "createdByName": "Alex Operator",
        "createdAt": "2026-06-17T15:04:05.000Z"
      }
    ],
    "createdAt": "2026-06-17T15:00:00.000Z",
    "updatedAt": "2026-06-17T15:04:05.000Z"
  }
}

GET/contacts/{id}

Retrieve a contact

Returns a single contact by id. A record belonging to another organization returns 404 rather than 403, so this can never confirm cross-tenant existence. Requires scope: contacts:read.

Parameters

Path

idrequired

string

The contact id.

Response 200

FieldTypeDescription

id

string

Unique identifier of the contact.

object

string

The object type. Always "contact".

name

string

Display name of the contact. Empty string when unset.

phone

string

Primary phone number. Empty string when unset.

email

string

Email address. Empty string when unset.

company

string

Company or organization name for the contact. Empty string when unset.

avatarUrl

string

URL of the contact's avatar image. Empty string when unset.

entity

enumchats | rooms | callCenter | both

Which surface(s) this contact belongs to. Any unrecognized or missing value normalizes to "both".

address

object

Structured address for a contact. fullAddress is read-only and recomputed server-side from the parts on every write.

address

string

Street address line.

unit

string

Unit, suite, or apartment.

city

string

state

string

zipCode

string

country

string

lat

number

Latitude, or null when unset.nullable

lng

number

Longitude, or null when unset.nullable

fullAddress

string

Server-computed single-line address. Read-only.

notes

array of object

Embedded notes attached to the contact.

id

string

text

string

createdBy

string

Identifier of the member who created the note.nullable

createdByName

string

Display name of the member who created the note.nullable

createdAt

string <date-time>

ISO-8601 timestamp when the note was created.nullable

createdAt

string <date-time>

ISO-8601 timestamp when the contact was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp when the contact was last updated.nullable

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/contacts/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "ct_8fJ2kLqWxr",
    "object": "contact",
    "name": "Jane Doe",
    "phone": "+14155551234",
    "email": "jane@example.com",
    "company": "Acme Clinic",
    "avatarUrl": "",
    "entity": "callCenter",
    "address": {
      "address": "123 Market St",
      "unit": "Suite 200",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94103",
      "country": "USA",
      "lat": 37.7793,
      "lng": -122.4193,
      "fullAddress": "123 Market St Suite 200, San Francisco, CA, 94103, USA"
    },
    "notes": [
      {
        "id": "nt_1",
        "text": "Prefers afternoon callbacks.",
        "createdBy": "usr_abc123",
        "createdByName": "Alex Operator",
        "createdAt": "2026-06-17T15:04:05.000Z"
      }
    ],
    "createdAt": "2026-06-17T15:00:00.000Z",
    "updatedAt": "2026-06-17T15:04:05.000Z"
  }
}

PATCH/contacts/{id}

Update a contact

Partially updates a contact. Only the fields supplied in the request body are rewritten. The name-or-phone rule is enforced against the merged result, so a contact can never end up without both. Requires scope: contacts:write.

Parameters

Path

idrequired

string

The unique identifier of the contact.

Request body

FieldTypeDescription

name

string

Display name. Max 120 characters.

phone

string

Primary phone number. Max 32 characters.

email

string

Email address. Max 120 characters.

company

string

Company or organization name. Max 120 characters.

avatarUrl

string

URL of the contact's avatar image. Max 600 characters.

entity

enumchats | rooms | callCenter | both

Which surface(s) this contact belongs to. Any unrecognized value normalizes to "both".

address

object

Address parts supplied on write. fullAddress is ignored on input and always recomputed server-side from these parts.

address

string

Street address line. Max 240 characters.

unit

string

Unit, suite, or apartment. Max 60 characters.

city

string

Max 120 characters.

state

string

Max 120 characters.

zipCode

string

Postal code. Max 20 characters. The alias "zip" is also accepted.

country

string

Max 120 characters.

lat

number

Latitude. Stored as null when not a finite number.nullable

lng

number

Longitude. Stored as null when not a finite number.nullable

Response 200

FieldTypeDescription

id

string

Unique identifier of the contact.

object

string

The object type. Always "contact".

name

string

Display name of the contact. Empty string when unset.

phone

string

Primary phone number. Empty string when unset.

email

string

Email address. Empty string when unset.

company

string

Company or organization name for the contact. Empty string when unset.

avatarUrl

string

URL of the contact's avatar image. Empty string when unset.

entity

enumchats | rooms | callCenter | both

Which surface(s) this contact belongs to. Any unrecognized or missing value normalizes to "both".

address

object

Structured address for a contact. fullAddress is read-only and recomputed server-side from the parts on every write.

address

string

Street address line.

unit

string

Unit, suite, or apartment.

city

string

state

string

zipCode

string

country

string

lat

number

Latitude, or null when unset.nullable

lng

number

Longitude, or null when unset.nullable

fullAddress

string

Server-computed single-line address. Read-only.

notes

array of object

Embedded notes attached to the contact.

id

string

text

string

createdBy

string

Identifier of the member who created the note.nullable

createdByName

string

Display name of the member who created the note.nullable

createdAt

string <date-time>

ISO-8601 timestamp when the note was created.nullable

createdAt

string <date-time>

ISO-8601 timestamp when the contact was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp when the contact was last updated.nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X PATCH https://api.genaya.com/v1/contacts/{id} \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Doe",
  "phone": "+14155551234",
  "email": "jane@example.com",
  "company": "Acme Clinic",
  "entity": "callCenter",
  "address": {
    "address": "123 Market St",
    "unit": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94103",
    "country": "USA",
    "lat": 37.7793,
    "lng": -122.4193
  }
}'

Example response

{
  "data": {
    "id": "ct_8fJ2kLqWxr",
    "object": "contact",
    "name": "Jane Doe",
    "phone": "+14155551234",
    "email": "jane@example.com",
    "company": "Acme Clinic",
    "avatarUrl": "",
    "entity": "callCenter",
    "address": {
      "address": "123 Market St",
      "unit": "Suite 200",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94103",
      "country": "USA",
      "lat": 37.7793,
      "lng": -122.4193,
      "fullAddress": "123 Market St Suite 200, San Francisco, CA, 94103, USA"
    },
    "notes": [
      {
        "id": "nt_1",
        "text": "Prefers afternoon callbacks.",
        "createdBy": "usr_abc123",
        "createdByName": "Alex Operator",
        "createdAt": "2026-06-17T15:04:05.000Z"
      }
    ],
    "createdAt": "2026-06-17T15:00:00.000Z",
    "updatedAt": "2026-06-17T15:04:05.000Z"
  }
}

DELETE/contacts/{id}

Delete a contact

Soft-deletes a contact by setting its deletedAt timestamp. The contact is thereafter excluded from list and retrieve responses. Requires scope: contacts:write.

Parameters

Path

idrequired

string

The unique identifier of the contact.

Response 200

FieldTypeDescription

id

string

Identifier of the deleted contact.

object

string

deleted

boolean

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X DELETE https://api.genaya.com/v1/contacts/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "",
    "object": "contact",
    "deleted": true
  }
}