Clients API | Genaya API Reference

Core

Clients

People and companies you serve (clients, patients, customers).

GET/clients

List clients

Returns a cursor-paginated list of clients in your organization, ordered by document id. Soft-deleted clients are excluded. Pass email or phone to look up a specific client server-side instead of paging the whole list. Requires scope: clients:read.

Parameters

Query

email

string

Filter to clients whose email is exactly this value. The value is normalized the way client emails are stored (trimmed and lowercased), so the match is case-insensitive. Use one lookup filter at a time - combining email with phone, or with from/to/updated_since, returns 400 (code conflicting_filters). Pagination (limit/starting_after) works unchanged within the filtered results.

phone

string

Filter to clients whose primary phone matches this value exactly. The raw value, its bare digits, and its E.164 variants (+15551234567 for 5551234567) are all tried, so pass the number in any of those forms; a number stored with other formatting only matches when you pass the identical formatting. Use one lookup filter at a time - combining phone with email, or with from/to/updated_since, returns 400 (code conflicting_filters). Pagination (limit/starting_after) works unchanged within the filtered results.

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/clients \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "7Qx2mF0aBcDeFgHiJkLm",
      "object": "client",
      "numericId": 1042,
      "uuid": "K7M3PQ",
      "title": "Dr.",
      "firstName": "Jordan",
      "lastName": "Avery",
      "fullName": "Jordan Avery",
      "company": "Avery Industries",
      "phone": "+14155550142",
      "secondaryPhone": "+14155550199",
      "email": "jordan.avery@example.com",
      "phoneNumbers": [
        {
          "number": "+14155550142",
          "normalized": "14155550142",
          "isPrimary": true
        },
        {
          "number": "+14155550199",
          "normalized": "14155550199",
          "isPrimary": false
        }
      ],
      "address": {
        "line1": "500 Market St",
        "unit": "Suite 400",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94105",
        "country": "US"
      },
      "fullAddress": "500 Market St, San Francisco, CA, 94105",
      "leadSource": "Website",
      "leadSourceId": "Website",
      "status": "active",
      "customFields": {
        "preferredContact": "email"
      },
      "organizationCompanyId": "cmp_9aF2",
      "organizationCompanyName": "Avery HVAC - North",
      "organizationCompanyLogoUrl": "https://storage.genaya.com/orgs/logos/north.png",
      "createdAt": "2026-06-17T14:32:00.000Z",
      "updatedAt": "2026-06-17T15:10:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/clients

Create a client

Creates a client. Provide at least one of firstName, lastName, company, email, or phone. If the contact matches an existing active client (by email, then phone, then secondary phone) that client is updated and returned instead of creating a duplicate - unless the body names a `company` and the matching client carries a different company name, in which case a separate client is created. Requires scope: clients:write.

Request body

FieldTypeDescription

uuid

string

Optional short UUID to assign. One is generated when omitted.

title

string

firstName

string

lastName

string

company

string

phone

string

secondaryPhone

string

email

string <email>

address

object

Canonical address sub-object. Individual keys are omitted when empty, and the whole object is omitted when no address fields are set.

line1

string

unit

string

city

string

state

string

zip

string

country

string

leadSource

string

How the client was acquired. Also populates leadSourceId.

status

string

Lifecycle status. Lowercased on save.

customFields

object

organizationCompanyId

string

Identifier of the company/branch to associate the client with.

organizationCompanyName

string

Display name of the associated company/branch.

organizationCompanyLogoUrl

string

Logo URL of the associated company/branch.

Response 201

FieldTypeDescription

idrequired

string

Unique identifier for the client.

objectrequired

string

The object type. Always "client".

numericId

integer

Org-scoped sequential client number assigned from the organization's numbering settings. Distinct from the string `id` (the record handle). Null until a number has been allocated.nullable

uuid

string

Stable short UUID assigned to the client record.

title

string

Salutation or title (e.g. Mr., Dr.).

firstName

string

lastName

string

fullName

string

Full display name as stored on the record.

company

string

phone

string

Primary phone number in E.164 or stored format.

secondaryPhone

string

email

string <email>

phoneNumbers

array of object

All phone numbers on the record, derived from the primary and secondary phone. The primary phone is flagged isPrimary. Read-only - managed via the phone and secondaryPhone fields.

number

string

The phone number as entered.

normalized

string

Digits-only normalization of the number. Null when it could not be derived.nullable

isPrimary

boolean

Whether this is the client's primary phone.

address

object

Canonical address sub-object. Individual keys are omitted when empty, and the whole object is omitted when no address fields are set.

line1

string

unit

string

city

string

state

string

zip

string

country

string

fullAddress

string

Derived single-line address (line1, city, state, zip joined by commas). Read-only - never accepted on create/update. Null when no address is set.nullable

leadSource

string

How the client was acquired. Null when not set.nullable

leadSourceId

string

Identifier of the lead source. Mirrors leadSource through the shared upsert path. Null when not set.nullable

status

string

Lifecycle status. Defaults to "active".

customFields

object

Organization-defined custom field values keyed by field id.

organizationCompanyId

string

Identifier of the company/branch the client is associated with. Null when unset.nullable

organizationCompanyName

string

Display name of the associated company/branch. Null when unset.nullable

organizationCompanyLogoUrl

string

Logo URL of the associated company/branch. Null when unset.nullable

createdAt

string <date-time>

nullable

updatedAt

string <date-time>

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/clients \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "firstName": "Jordan",
  "lastName": "Avery",
  "email": "jordan.avery@example.com",
  "phone": "+14155550142",
  "address": {
    "line1": "500 Market St",
    "unit": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US"
  },
  "leadSource": "Website"
}'

Example response

{
  "data": {
    "id": "7Qx2mF0aBcDeFgHiJkLm",
    "object": "client",
    "numericId": 1042,
    "uuid": "K7M3PQ",
    "title": "Dr.",
    "firstName": "Jordan",
    "lastName": "Avery",
    "fullName": "Jordan Avery",
    "company": "Avery Industries",
    "phone": "+14155550142",
    "secondaryPhone": "+14155550199",
    "email": "jordan.avery@example.com",
    "phoneNumbers": [
      {
        "number": "+14155550142",
        "normalized": "14155550142",
        "isPrimary": true
      },
      {
        "number": "+14155550199",
        "normalized": "14155550199",
        "isPrimary": false
      }
    ],
    "address": {
      "line1": "500 Market St",
      "unit": "Suite 400",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "fullAddress": "500 Market St, San Francisco, CA, 94105",
    "leadSource": "Website",
    "leadSourceId": "Website",
    "status": "active",
    "customFields": {
      "preferredContact": "email"
    },
    "organizationCompanyId": "cmp_9aF2",
    "organizationCompanyName": "Avery HVAC - North",
    "organizationCompanyLogoUrl": "https://storage.genaya.com/orgs/logos/north.png",
    "createdAt": "2026-06-17T14:32:00.000Z",
    "updatedAt": "2026-06-17T15:10:00.000Z"
  }
}

GET/clients/{id}

Retrieve a client

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

Parameters

Path

idrequired

string

The client id.

Response 200

FieldTypeDescription

idrequired

string

Unique identifier for the client.

objectrequired

string

The object type. Always "client".

numericId

integer

Org-scoped sequential client number assigned from the organization's numbering settings. Distinct from the string `id` (the record handle). Null until a number has been allocated.nullable

uuid

string

Stable short UUID assigned to the client record.

title

string

Salutation or title (e.g. Mr., Dr.).

firstName

string

lastName

string

fullName

string

Full display name as stored on the record.

company

string

phone

string

Primary phone number in E.164 or stored format.

secondaryPhone

string

email

string <email>

phoneNumbers

array of object

All phone numbers on the record, derived from the primary and secondary phone. The primary phone is flagged isPrimary. Read-only - managed via the phone and secondaryPhone fields.

number

string

The phone number as entered.

normalized

string

Digits-only normalization of the number. Null when it could not be derived.nullable

isPrimary

boolean

Whether this is the client's primary phone.

address

object

Canonical address sub-object. Individual keys are omitted when empty, and the whole object is omitted when no address fields are set.

line1

string

unit

string

city

string

state

string

zip

string

country

string

fullAddress

string

Derived single-line address (line1, city, state, zip joined by commas). Read-only - never accepted on create/update. Null when no address is set.nullable

leadSource

string

How the client was acquired. Null when not set.nullable

leadSourceId

string

Identifier of the lead source. Mirrors leadSource through the shared upsert path. Null when not set.nullable

status

string

Lifecycle status. Defaults to "active".

customFields

object

Organization-defined custom field values keyed by field id.

organizationCompanyId

string

Identifier of the company/branch the client is associated with. Null when unset.nullable

organizationCompanyName

string

Display name of the associated company/branch. Null when unset.nullable

organizationCompanyLogoUrl

string

Logo URL of the associated company/branch. Null when unset.nullable

createdAt

string <date-time>

nullable

updatedAt

string <date-time>

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/clients/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "7Qx2mF0aBcDeFgHiJkLm",
    "object": "client",
    "numericId": 1042,
    "uuid": "K7M3PQ",
    "title": "Dr.",
    "firstName": "Jordan",
    "lastName": "Avery",
    "fullName": "Jordan Avery",
    "company": "Avery Industries",
    "phone": "+14155550142",
    "secondaryPhone": "+14155550199",
    "email": "jordan.avery@example.com",
    "phoneNumbers": [
      {
        "number": "+14155550142",
        "normalized": "14155550142",
        "isPrimary": true
      },
      {
        "number": "+14155550199",
        "normalized": "14155550199",
        "isPrimary": false
      }
    ],
    "address": {
      "line1": "500 Market St",
      "unit": "Suite 400",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "fullAddress": "500 Market St, San Francisco, CA, 94105",
    "leadSource": "Website",
    "leadSourceId": "Website",
    "status": "active",
    "customFields": {
      "preferredContact": "email"
    },
    "organizationCompanyId": "cmp_9aF2",
    "organizationCompanyName": "Avery HVAC - North",
    "organizationCompanyLogoUrl": "https://storage.genaya.com/orgs/logos/north.png",
    "createdAt": "2026-06-17T14:32:00.000Z",
    "updatedAt": "2026-06-17T15:10:00.000Z"
  }
}

PATCH/clients/{id}

Update a client

Updates an existing client. Ownership is verified before the write, so a client belonging to another organization returns 404. Requires scope: clients:write.

Parameters

Path

idrequired

string

The client id.

Request body

FieldTypeDescription

uuid

string

title

string

firstName

string

lastName

string

company

string

phone

string

secondaryPhone

string

email

string <email>

address

object

Canonical address sub-object. Individual keys are omitted when empty, and the whole object is omitted when no address fields are set.

line1

string

unit

string

city

string

state

string

zip

string

country

string

leadSource

string

status

string

customFields

object

organizationCompanyId

string

organizationCompanyName

string

organizationCompanyLogoUrl

string

Response 200

FieldTypeDescription

idrequired

string

Unique identifier for the client.

objectrequired

string

The object type. Always "client".

numericId

integer

Org-scoped sequential client number assigned from the organization's numbering settings. Distinct from the string `id` (the record handle). Null until a number has been allocated.nullable

uuid

string

Stable short UUID assigned to the client record.

title

string

Salutation or title (e.g. Mr., Dr.).

firstName

string

lastName

string

fullName

string

Full display name as stored on the record.

company

string

phone

string

Primary phone number in E.164 or stored format.

secondaryPhone

string

email

string <email>

phoneNumbers

array of object

All phone numbers on the record, derived from the primary and secondary phone. The primary phone is flagged isPrimary. Read-only - managed via the phone and secondaryPhone fields.

number

string

The phone number as entered.

normalized

string

Digits-only normalization of the number. Null when it could not be derived.nullable

isPrimary

boolean

Whether this is the client's primary phone.

address

object

Canonical address sub-object. Individual keys are omitted when empty, and the whole object is omitted when no address fields are set.

line1

string

unit

string

city

string

state

string

zip

string

country

string

fullAddress

string

Derived single-line address (line1, city, state, zip joined by commas). Read-only - never accepted on create/update. Null when no address is set.nullable

leadSource

string

How the client was acquired. Null when not set.nullable

leadSourceId

string

Identifier of the lead source. Mirrors leadSource through the shared upsert path. Null when not set.nullable

status

string

Lifecycle status. Defaults to "active".

customFields

object

Organization-defined custom field values keyed by field id.

organizationCompanyId

string

Identifier of the company/branch the client is associated with. Null when unset.nullable

organizationCompanyName

string

Display name of the associated company/branch. Null when unset.nullable

organizationCompanyLogoUrl

string

Logo URL of the associated company/branch. Null when unset.nullable

createdAt

string <date-time>

nullable

updatedAt

string <date-time>

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/clients/{id} \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Avery Industries LLC",
  "status": "active"
}'

Example response

{
  "data": {
    "id": "7Qx2mF0aBcDeFgHiJkLm",
    "object": "client",
    "numericId": 1042,
    "uuid": "K7M3PQ",
    "title": "Dr.",
    "firstName": "Jordan",
    "lastName": "Avery",
    "fullName": "Jordan Avery",
    "company": "Avery Industries",
    "phone": "+14155550142",
    "secondaryPhone": "+14155550199",
    "email": "jordan.avery@example.com",
    "phoneNumbers": [
      {
        "number": "+14155550142",
        "normalized": "14155550142",
        "isPrimary": true
      },
      {
        "number": "+14155550199",
        "normalized": "14155550199",
        "isPrimary": false
      }
    ],
    "address": {
      "line1": "500 Market St",
      "unit": "Suite 400",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "fullAddress": "500 Market St, San Francisco, CA, 94105",
    "leadSource": "Website",
    "leadSourceId": "Website",
    "status": "active",
    "customFields": {
      "preferredContact": "email"
    },
    "organizationCompanyId": "cmp_9aF2",
    "organizationCompanyName": "Avery HVAC - North",
    "organizationCompanyLogoUrl": "https://storage.genaya.com/orgs/logos/north.png",
    "createdAt": "2026-06-17T14:32:00.000Z",
    "updatedAt": "2026-06-17T15:10:00.000Z"
  }
}

DELETE/clients/{id}

Delete a client

Soft-deletes a client and revokes any client portal access tokens for that client. Requires scope: clients:write.

Parameters

Path

idrequired

string

The client id.

Response 200

FieldTypeDescription

idrequired

string

objectrequired

string

deletedrequired

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/clients/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "7Qx2mF0aBcDeFgHiJkLm",
    "object": "client",
    "deleted": true
  }
}