Leads API | Genaya API Reference

Core

Leads

Lead rows inside a lead table.

GET/lead-tables/{tableId}/leads

List leads in a table

Returns a cursor-paginated list of lead rows belonging to the given lead table, ordered by document id. Soft-deleted rows are excluded. Reads Firestore directly so a just-created row appears immediately. Requires scope: leads:read.

Parameters

Path

tableIdrequired

string

The id of the parent lead table.

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

404No such resource in this organization

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/lead-tables/{tableId}/leads \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "lead_9fQ2x7TzKp",
      "object": "lead",
      "tableId": "tbl_3KdR8mVnQ1",
      "tabId": "tab_new",
      "fields": {
        "firstName": "Jordan",
        "lastName": "Rivera",
        "email": "jordan.rivera@example.com",
        "phone": "+15551234567"
      },
      "starred": false,
      "displayOrder": 1,
      "createdAt": "2026-06-17T14:32:10.000Z",
      "updatedAt": "2026-06-17T14:32:10.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/lead-tables/{tableId}/leads

Create a lead

Creates a new lead row in the given table. The row is fully populated in one call by writing the dynamic `fields` cell values verbatim. The target tab resolves from an explicit `tabId` (must match a tab on the table) or falls back to the table's first tab. The writer is the API key's issuing member. Requires scope: leads:write.

Parameters

Path

tableIdrequired

string

The id of the parent lead table.

Request body

FieldTypeDescription

tabId

string

Optional tab to file the row under. Must match a tab on the table; otherwise the table's first tab is used.

fields

object

Dynamic column cell values keyed by each column's nameId. Stored verbatim. Reserved keys are ignored.

displayOrder

number

Optional manual sort position within the table.

Response 201

FieldTypeDescription

idrequired

string

Unique identifier for the lead row.

objectrequired

string

The object type. Always "lead".

tableIdrequired

string

The id of the parent lead table this row belongs to.

tabId

string

The id of the tab this row is filed under, or null.nullable

fieldsrequired

object

Dynamic column cell values keyed by each column's nameId. Values are surfaced raw (string, number, array, etc.) since the column type is not coerced here.

starredrequired

boolean

Whether the row is starred. Defaults to false.

displayOrder

number

Manual sort position within the table. Omitted when the row has no explicit display order.

createdAt

string <date-time>

ISO-8601 timestamp when the row was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp when the row 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

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/lead-tables/{tableId}/leads \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "tabId": "tab_new",
  "fields": {
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan.rivera@example.com",
    "phone": "+15551234567"
  },
  "displayOrder": 1
}'

Example response

{
  "data": {
    "id": "lead_9fQ2x7TzKp",
    "object": "lead",
    "tableId": "tbl_3KdR8mVnQ1",
    "tabId": "tab_new",
    "fields": {
      "firstName": "Jordan",
      "lastName": "Rivera",
      "email": "jordan.rivera@example.com",
      "phone": "+15551234567"
    },
    "starred": false,
    "displayOrder": 1,
    "createdAt": "2026-06-17T14:32:10.000Z",
    "updatedAt": "2026-06-17T14:32:10.000Z"
  }
}

GET/lead-tables/{tableId}/leads/{leadId}

Retrieve a lead

Returns a single lead row by id. The row must belong to both the caller's organization and the table in the path, so a valid row id under the wrong table returns 404. Requires scope: leads:read.

Parameters

Path

tableIdrequired

string

leadIdrequired

string

Response 200

FieldTypeDescription

idrequired

string

Unique identifier for the lead row.

objectrequired

string

The object type. Always "lead".

tableIdrequired

string

The id of the parent lead table this row belongs to.

tabId

string

The id of the tab this row is filed under, or null.nullable

fieldsrequired

object

Dynamic column cell values keyed by each column's nameId. Values are surfaced raw (string, number, array, etc.) since the column type is not coerced here.

starredrequired

boolean

Whether the row is starred. Defaults to false.

displayOrder

number

Manual sort position within the table. Omitted when the row has no explicit display order.

createdAt

string <date-time>

ISO-8601 timestamp when the row was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp when the row 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/lead-tables/{tableId}/leads/{leadId} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "lead_9fQ2x7TzKp",
    "object": "lead",
    "tableId": "tbl_3KdR8mVnQ1",
    "tabId": "tab_new",
    "fields": {
      "firstName": "Jordan",
      "lastName": "Rivera",
      "email": "jordan.rivera@example.com",
      "phone": "+15551234567"
    },
    "starred": false,
    "displayOrder": 1,
    "createdAt": "2026-06-17T14:32:10.000Z",
    "updatedAt": "2026-06-17T14:32:10.000Z"
  }
}

PATCH/lead-tables/{tableId}/leads/{leadId}

Update a lead

Updates a lead row's dynamic cells and/or its `tabId`, `starred`, and `displayOrder`. The `fields` map is merged onto the row verbatim (raw values, no type coercion). Reserved keys can never be written through `fields`. A supplied non-empty `tabId` must match a tab on the table. Requires scope: leads:write.

Parameters

Path

tableIdrequired

string

The id of the parent lead table.

leadIdrequired

string

The id of the lead row.

Request body

FieldTypeDescription

fields

object

Dynamic column cell values to merge onto the row, keyed by each column's nameId. Stored verbatim. Reserved keys are ignored.

tabId

string

Tab to move the row to. A non-empty value must match a tab on the table; an empty value clears the tab.nullable

starred

boolean

Whether the row is starred.

displayOrder

number

Manual sort position within the table. Must be a number.

Response 200

FieldTypeDescription

idrequired

string

Unique identifier for the lead row.

objectrequired

string

The object type. Always "lead".

tableIdrequired

string

The id of the parent lead table this row belongs to.

tabId

string

The id of the tab this row is filed under, or null.nullable

fieldsrequired

object

Dynamic column cell values keyed by each column's nameId. Values are surfaced raw (string, number, array, etc.) since the column type is not coerced here.

starredrequired

boolean

Whether the row is starred. Defaults to false.

displayOrder

number

Manual sort position within the table. Omitted when the row has no explicit display order.

createdAt

string <date-time>

ISO-8601 timestamp when the row was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp when the row 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/lead-tables/{tableId}/leads/{leadId} \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "email": "jordan.rivera@newmail.com"
  },
  "starred": true,
  "displayOrder": 2
}'

Example response

{
  "data": {
    "id": "lead_9fQ2x7TzKp",
    "object": "lead",
    "tableId": "tbl_3KdR8mVnQ1",
    "tabId": "tab_new",
    "fields": {
      "firstName": "Jordan",
      "lastName": "Rivera",
      "email": "jordan.rivera@example.com",
      "phone": "+15551234567"
    },
    "starred": false,
    "displayOrder": 1,
    "createdAt": "2026-06-17T14:32:10.000Z",
    "updatedAt": "2026-06-17T14:32:10.000Z"
  }
}

DELETE/lead-tables/{tableId}/leads/{leadId}

Delete a lead

Soft-deletes a lead row (sets `deletedAt` so it drops out of every read surface while staying recoverable). Returns 404 if the row is missing, cross-organization, belongs to a different table, or already soft-deleted. Requires scope: leads:write.

Parameters

Path

tableIdrequired

string

The id of the parent lead table.

leadIdrequired

string

The id of the lead row.

Response 200

FieldTypeDescription

idrequired

string

The id of the soft-deleted lead row.

objectrequired

string

The object type. Always "lead".

deletedrequired

boolean

Always true on a successful delete.

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

429Rate limited

500Unexpected server error

curl -X DELETE https://api.genaya.com/v1/lead-tables/{tableId}/leads/{leadId} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "lead_9fQ2x7TzKp",
    "object": "lead",
    "deleted": true
  }
}