Internal API

Contacts

45 endpoints.

GET/api/v1/internal/businesses/{business_id}/contacts

List contacts

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`status`	query	`string \| null`
`lifecycle_stage`	query	`string \| null`
`signal`	query	`string \| null`	Filter by signal: hot,warm,cool,new,unassigned
`touch`	query	`string \| null`	Filter by touch: responsive,slow,unresponsive,ghosted,unassigned
`stage`	query	`string \| null`	Filter by stage: new,engaged,booked,returning,lapsed,lost,unassigned
`needs_attention`	query	`boolean \| null`	Filter contacts requiring supervisory attention
`identity_resolution_status`	query	`string \| null`
`include_deleted`	query	`boolean`	default false
`source`	query	`string \| null`
`created_after`	query	`string (date-time) \| null`
`created_before`	query	`string (date-time) \| null`
`updated_after`	query	`string (date-time) \| null`
`sort`	query	`string`	Sort order. 'last_activity' (default) surfaces the most recent conversation first; also accepts any contact column (created_at, updated_at, ...). default "last_activity"
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ContactData__

Field Type Description

request_idrequired string

success true default true

datarequired

ContactData[]

ContactData[] fields

Field	Type	Description
`id`required	`string`
`business_id`required	`string`
`consumer_id`	`string \| null`
`first_name`	`string \| null`
`last_name`	`string \| null`
`display_name`	`string \| null`
`status`required	`string`
`lifecycle_stage`required	`string`
`identity_resolution_status`required	`string`
`signal`	`string`	default "unassigned"
`touch`	`string`	default "unassigned"
`stage`	`string`	default "unassigned"
`engagement_score`	`integer \| null`
`purchase_intent`	`integer \| null`
`primary_email`	`string \| null`
`primary_phone`	`string \| null`
`last_contacted_at`	`string (date-time) \| null`
`last_replied_at`	`string (date-time) \| null`
`last_inbound_at`	`string (date-time) \| null`
`last_outbound_at`	`string (date-time) \| null`
`needs_attention`	`boolean`	default false
`needs_attention_reason`	`string \| null`
`needs_attention_at`	`string (date-time) \| null`
`metadata_`	`object`
`is_deleted`	`boolean`	default false
`deleted_at`	`string (date-time) \| null`
`merged_into_contact_id`	`string \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`
`first_source_type`	`string \| null`
`first_source_detail`	`string \| null`
`first_source_message`	`string \| null`
`latest_insight`	`LatestInsightSummary \| null`	LatestInsightSummary fields LatestInsightSummary (not expanded)
`conversation_id`	`string \| null`
`message_count`	`integer`	default 0
`auto_contact_enabled`	`boolean`	default false
`outreach_suppressed`	`boolean`	default false

metadata

ResponseMetadata | null

ResponseMetadata fields

Field Type Description

pagination

PaginationMetadata | null

PaginationMetadata fields

Field	Type	Description
`limit`required	`integer`
`next_cursor`	`string \| null`
`prev_cursor`	`string \| null`
`has_more`required	`boolean`
`has_prev`	`boolean`	default false
`total_count`	`integer \| null`

status_counts

object | null

object | null fields

Map of string to integer

lifecycle_counts

LifecycleCounts | null

LifecycleCounts fields

Field	Type	Description
`lead`	`integer`	default 0
`prospect`	`integer`	default 0
`customer`	`integer`	default 0
`former_customer`	`integer`	default 0

classification_counts

ClassificationCounts | null

ClassificationCounts fields

Field	Type	Description
`signal`	`object`	object fields Nested object (not expanded)
`touch`	`object`	object fields Nested object (not expanded)
`stage`	`object`	object fields Nested object (not expanded)

meta

ResponseMeta | null

ResponseMeta fields

Field	Type	Description
`total`	`integer \| null`
`total_count`	`integer \| null`
`page`	`integer \| null`
`per_page`	`integer \| null`

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts

Create contact

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactCreateBody

Field Type Description

first_name string | null

last_name string | null

display_name string | null

email string | null

phone string | null

emails

ContactEmailInputBody[]

ContactEmailInputBody[] fields

Field	Type	Description
`email`required	`string`
`source`	`string \| null`
`is_primary`	`boolean`	default false

phones

ContactPhoneInputBody[]

ContactPhoneInputBody[] fields

Field	Type	Description
`phone`required	`string`
`source`	`string \| null`
`is_primary`	`boolean`	default false

status string default "active"

lifecycle_stage string default "lead"

metadata_ object | null

source

ContactSourceBody | null

ContactSourceBody fields

Field	Type	Description
`contact_source_type`required	`ContactSourceType`
`contact_source_detail`	`string \| null`
`external_ref_id`	`string \| null`

consent

ContactConsentBody | null

ContactConsentBody fields

Field	Type	Description
`transactional_sms`	`boolean \| null`
`marketing_sms`	`boolean \| null`
`marketing_email`	`boolean \| null`
`tos_privacy`	`boolean \| null`

ai_initiate boolean default false

Responses

201Successful Response

application/jsonSuccessResponse_ContactOutcomeData_

Field Type Description

request_idrequired string

success true default true

datarequired

ContactOutcomeData

ContactOutcomeData fields

Field Type Description

contactrequired

ContactData

ContactData fields

ContactData, expanded above.

operationrequired string

consumer_link_statusrequired string

duplicate_flagged boolean default false

identity_review_id string | null

duplicate_review_id string | null

ai_initiation

AiInitiationResult | null

AiInitiationResult fields

Field	Type	Description
`dispatched`required	`boolean`
`reason`	`string \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}

Get contact detail

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData`	ContactData fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PATCH/api/v1/internal/businesses/{business_id}/contacts/{contact_id}

Update contact

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactUpdateBody

Field	Type	Description
`first_name`	`string \| null`
`last_name`	`string \| null`
`display_name`	`string \| null`
`status`	`string \| null`
`lifecycle_stage`	`string \| null`
`signal`	`string \| null`
`touch`	`string \| null`
`stage`	`string \| null`
`metadata_`	`object \| null`
`last_contacted_at`	`string (date-time) \| null`
`auto_contact_enabled`	`boolean \| null`
`outreach_suppressed`	`boolean \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData`	ContactData fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/internal/businesses/{business_id}/contacts/{contact_id}

Delete contact

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

204Successful Response

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PATCH/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/classification

Override contact classification

Override one or more classification dimensions for the contact. Any field omitted in the body is left unchanged. Each changed dimension lands a row in `contact_classification_history` with `changed_by="user:api"` and the supplied `reason`.

Manual overrides are NOT sticky — the next AI classification pass (triggered by inbound messages or DELIVERED/READ status events) may overwrite them. To preserve a manual value, take the conversation out of AUTONOMOUS AI mode.

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonClassifyBody

Field	Type	Description
`signal`	`string \| null`
`touch`	`string \| null`
`stage`	`string \| null`
`reason`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData`	ContactData fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/classification-history

Get classification history

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`field`	query	`string \| null`	Filter by: signal, touch, stage
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ClassificationHistoryItem__

Field Type Description

request_idrequired string

success true default true

datarequired

ClassificationHistoryItem[]

ClassificationHistoryItem[] fields

Field	Type	Description
`type`	`string`	default "classification"
`field`required	`string`
`old_value`	`string \| null`
`new_value`required	`string`
`changed_by`required	`string`
`reason`	`string \| null`
`created_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/classify

Manually classify a contact (legacy POST alias)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonClassifyBody

ClassifyBody, expanded above.

Responses

200Successful Response

application/jsonSuccessResponse_ContactData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData`	ContactData fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/conversation

Get this contact's conversation

Returns the conversation for this contact's consumer, or `data: null` with 200 when none exists yet. 404 is reserved for the contact itself being missing from this business — the frontend should branch on `data == null`, not on status code.

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_Union_ConversationData__NoneType__

Field Type Description

request_idrequired string

success true default true

datarequired

ConversationData | null

ConversationData fields

Field Type Description

idrequired string

consumer_id string | null

statusrequired string

assigned_to integer | null

ai_enabled boolean default true

ai_mode string default "AUTONOMOUS"

last_message_at string (date-time) | null

last_message_preview string | null

last_message_channel string | null

unread_count integer default 0

message_count integer default 0

snoozed_until string (date-time) | null

created_atrequired string (date-time)

updated_atrequired string (date-time)

reply_channel

ReplyChannelData | null

ReplyChannelData fields

Field	Type	Description
`default`	`string \| null`
`available`	`string[]`	default [] string[] fields Nested object (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emails

List contact emails

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ContactEmailData__

Field Type Description

request_idrequired string

success true default true

datarequired

ContactEmailData[]

ContactEmailData[] fields

Field	Type	Description
`id`required	`string`
`business_contact_id`required	`string`
`business_id`required	`string`
`raw_input`	`string \| null`
`email`required	`string`
`verified_at`	`string (date-time) \| null`
`source`	`string \| null`
`is_deleted`	`boolean`	default false
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emails

Add email to contact

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactEmailCreateBody

Field	Type	Description
`email`required	`string`
`source`	`string \| null`

Responses

201Successful Response

application/jsonSuccessResponse_ContactEmailAddResult_

Field Type Description

request_idrequired string

success true default true

datarequired

ContactEmailAddResult

ContactEmailAddResult fields

Field	Type	Description
`email`required	`ContactEmailData`	ContactEmailData fields ContactEmailData, expanded above.
`identity_review_id`	`string \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PATCH/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emails/{email_id}

Update contact email

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`email_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactEmailPatchBody

Field	Type	Description
`email`	`string \| null`
`source`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactEmailUpdateResult_

Field Type Description

request_idrequired string

success true default true

datarequired

ContactEmailUpdateResult

ContactEmailUpdateResult fields

Field	Type	Description
`email`required	`ContactEmailData`	ContactEmailData fields ContactEmailData, expanded above.
`identity_review_id`	`string \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emails/{email_id}

Remove email from contact

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`email_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

204Successful Response

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/emails/{email_id}/set-primary

Set primary email

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`email_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData`	ContactData fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/insights

List contact insights

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`include_dismissed`	query	`boolean`	default false
`priority`	query	`string \| null`
`limit`	query	`integer`	default 20
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ContactInsightData__

Field Type Description

request_idrequired string

success true default true

datarequired

ContactInsightData[]

ContactInsightData[] fields

Field	Type	Description
`id`required	`string`
`contact_id`required	`string`
`business_id`required	`string`
`insight_type`required	`string`
`title`required	`string`
`body`required	`string`
`priority`required	`string`
`action_type`	`string \| null`
`action_data`	`object \| null`
`is_dismissed`	`boolean`	default false
`expires_at`	`string (date-time) \| null`
`created_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/insights/{insight_id}

Get a contact insight

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`insight_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactInsightData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactInsightData`	ContactInsightData fields ContactInsightData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/insights/{insight_id}/dismiss

Dismiss a contact insight

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`insight_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactInsightData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactInsightData`	ContactInsightData fields ContactInsightData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/needs-attention

Resolve contact needs-attention overlay

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`re_enable_ai`	query	`boolean`	default false
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonobject

Map of string to boolean

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/opt-in

Record opt-in

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonOptInOutBody

Field	Type	Description
`channel`required	`string`
`source`required	`string`
`occurred_at`	`string (date-time) \| null`
`idempotency_key`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactPreferenceData_

Field Type Description

request_idrequired string

success true default true

datarequired

ContactPreferenceData

ContactPreferenceData fields

Field	Type	Description
`id`required	`string`
`business_contact_id`required	`string`
`transactional_sms_opt_in_at`	`string (date-time) \| null`
`transactional_sms_opt_out_at`	`string (date-time) \| null`
`marketing_sms_opt_in_at`	`string (date-time) \| null`
`marketing_sms_opt_out_at`	`string (date-time) \| null`
`marketing_email_opt_in_at`	`string (date-time) \| null`
`marketing_email_opt_out_at`	`string (date-time) \| null`
`tos_privacy_accepted_at`	`string (date-time) \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/opt-out

Record opt-out

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonOptInOutBody

OptInOutBody, expanded above.

Responses

200Successful Response

application/jsonSuccessResponse_ContactPreferenceData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactPreferenceData`	ContactPreferenceData fields ContactPreferenceData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phones

List contact phones

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ContactPhoneData__

Field Type Description

request_idrequired string

success true default true

datarequired

ContactPhoneData[]

ContactPhoneData[] fields

Field	Type	Description
`id`required	`string`
`business_contact_id`required	`string`
`business_id`required	`string`
`raw_input`	`string \| null`
`phone`required	`string`
`phone_type`	`string \| null`
`country_code`	`string \| null`
`verified_at`	`string (date-time) \| null`
`source`	`string \| null`
`is_deleted`	`boolean`	default false
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phones

Add phone to contact

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactPhoneCreateBody

Field	Type	Description
`phone`required	`string`
`source`	`string \| null`

Responses

201Successful Response

application/jsonSuccessResponse_ContactPhoneAddResult_

Field Type Description

request_idrequired string

success true default true

datarequired

ContactPhoneAddResult

ContactPhoneAddResult fields

Field	Type	Description
`phone`required	`ContactPhoneData`	ContactPhoneData fields ContactPhoneData, expanded above.
`identity_review_id`	`string \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PATCH/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phones/{phone_id}

Update contact phone

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`phone_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactPhonePatchBody

Field	Type	Description
`phone`	`string \| null`
`phone_type`	`string \| null`
`country_code`	`string \| null`
`source`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactPhoneUpdateResult_

Field Type Description

request_idrequired string

success true default true

datarequired

ContactPhoneUpdateResult

ContactPhoneUpdateResult fields

Field	Type	Description
`phone`required	`ContactPhoneData`	ContactPhoneData fields ContactPhoneData, expanded above.
`identity_review_id`	`string \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phones/{phone_id}

Remove phone from contact

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`phone_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

204Successful Response

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/phones/{phone_id}/set-primary

Set primary phone

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`phone_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData`	ContactData fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/preferences

Get preferences

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactPreferenceData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactPreferenceData`	ContactPreferenceData fields ContactPreferenceData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/reassess

Trigger a fresh AI classification pass

Publishes a manual `ClassificationRequest` for this contact's consumer. The classification consumer picks it up out-of-band and writes back signal/touch/stage + a fresh `latest_insight`; expect the new values to land within seconds. Returns the current contact snapshot — poll the same contact-detail endpoint to see the updated classification.

Returns 202 even when Kafka is disabled — the next inbound message will pick the contact up; the response includes the current state regardless.

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

202Successful Response

application/jsonSuccessResponse_ContactData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData`	ContactData fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/score-history

Get engagement score history

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ScoreHistoryItem__

Field Type Description

request_idrequired string

success true default true

datarequired

ScoreHistoryItem[]

ScoreHistoryItem[] fields

Field	Type	Description
`engagement_score`required	`integer`
`purchase_intent`	`integer \| null`
`model_version`	`string \| null`
`reasoning`	`string \| null`
`input_signals`	`object \| null`
`created_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/sources

List sources

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ContactSourceData__

Field Type Description

request_idrequired string

success true default true

datarequired

ContactSourceData[]

ContactSourceData[] fields

Field	Type	Description
`id`required	`string`
`business_contact_id`required	`string`
`contact_source_type`required	`ContactSourceType`
`contact_source_detail`	`string \| null`
`external_ref_id`	`string \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/{contact_id}/sources

Add source

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`contact_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactSourceCreateBody

Field	Type	Description
`contact_source_type`required	`ContactSourceType`
`contact_source_detail`	`string \| null`
`external_ref_id`	`string \| null`

Responses

201Successful Response

application/jsonSuccessResponse_ContactSourceData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactSourceData`	ContactSourceData fields ContactSourceData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/export

Export contacts as CSV

Stream every matching contact as a CSV file (one server request, no client-side paging).

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`q`	query	`string \| null`	Optional search query; when set, matches the search view
`status`	query	`string \| null`
`lifecycle_stage`	query	`string \| null`
`signal`	query	`string \| null`
`touch`	query	`string \| null`
`stage`	query	`string \| null`
`needs_attention`	query	`boolean \| null`
`identity_resolution_status`	query	`string \| null`
`include_deleted`	query	`boolean`	default false
`source`	query	`string \| null`
`created_after`	query	`string (date-time) \| null`
`created_before`	query	`string (date-time) \| null`
`updated_after`	query	`string (date-time) \| null`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonany

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/lookup

Lookup contact by email/phone

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactLookupBody

Field	Type	Description
`email`	`string \| null`
`phone`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactLookupResult_

Field Type Description

request_idrequired string

success true default true

datarequired

ContactLookupResult

ContactLookupResult fields

Field	Type	Description
`match_type`required	`string`
`contacts`required	`ContactData[]`	ContactData[] fields ContactData (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/contacts/merge

Merge contacts

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactMergeBody

Field	Type	Description
`surviving_contact_id`required	`string (uuid)`
`merged_contact_id`required	`string (uuid)`
`field_resolutions`	`object \| null`	object \| null fields Map of string to string
`merge_reason`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ContactData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData`	ContactData fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/needs-attention

List contacts needing attention

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`limit`	query	`integer`	default 10
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_NeedsAttentionData_

Field Type Description

request_idrequired string

success true default true

datarequired

NeedsAttentionData

NeedsAttentionData fields

Field	Type	Description
`items`required	`NeedsAttentionItem[]`	NeedsAttentionItem[] fields NeedsAttentionItem (not expanded)
`total`required	`integer`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/pipeline-summary

Get pipeline summary

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_PipelineSummaryData_

Field Type Description

request_idrequired string

success true default true

datarequired

PipelineSummaryData

PipelineSummaryData fields

Field	Type	Description
`summary`required	`string`
`stats`required	`object`
`generated_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/search

Search contacts

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`q`required	query	`string`
`status`	query	`string \| null`
`lifecycle_stage`	query	`string \| null`
`signal`	query	`string \| null`	Filter by signal: hot,warm,cool,new,unassigned
`touch`	query	`string \| null`	Filter by touch: responsive,slow,unresponsive,ghosted,unassigned
`stage`	query	`string \| null`	Filter by stage: new,engaged,booked,returning,lapsed,lost,unassigned
`needs_attention`	query	`boolean \| null`	Filter contacts requiring supervisory attention
`identity_resolution_status`	query	`string \| null`
`include_deleted`	query	`boolean`	default false
`source`	query	`string \| null`
`created_after`	query	`string (date-time) \| null`
`created_before`	query	`string (date-time) \| null`
`updated_after`	query	`string (date-time) \| null`
`sort`	query	`string`	default "relevance"
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ContactData__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactData[]`	ContactData[] fields ContactData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/contacts/stats

Get classification stats

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`status`	query	`string \| null`
`lifecycle_stage`	query	`string \| null`
`signal`	query	`string \| null`
`touch`	query	`string \| null`
`stage`	query	`string \| null`
`needs_attention`	query	`boolean \| null`
`identity_resolution_status`	query	`string \| null`
`source`	query	`string \| null`
`created_after`	query	`string (date-time) \| null`
`created_before`	query	`string (date-time) \| null`
`updated_after`	query	`string (date-time) \| null`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ClassificationStatsData_

Field Type Description

request_idrequired string

success true default true

datarequired

ClassificationStatsData

ClassificationStatsData fields

Field	Type	Description
`total`required	`integer`
`signal`required	`object`	object fields Map of string to integer
`touch`required	`object`	object fields Map of string to integer
`stage`required	`object`	object fields Map of string to integer
`lifecycle_stage`required	`object`	object fields Map of string to integer

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PUT/api/v1/internal/businesses/{business_id}/contacts/upsert

Upsert contact

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonContactCreateBody

ContactCreateBody, expanded above.

Responses

200Successful Response

application/jsonSuccessResponse_ContactOutcomeData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ContactOutcomeData`	ContactOutcomeData fields ContactOutcomeData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/duplicate-reviews

List duplicate reviews

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`status`	query	`string \| null`
`created_after`	query	`string (date-time) \| null`
`created_before`	query	`string (date-time) \| null`
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_DuplicateReviewData__

Field Type Description

request_idrequired string

success true default true

datarequired

DuplicateReviewData[]

DuplicateReviewData[] fields

Field	Type	Description
`id`required	`string`
`business_id`required	`string`
`contact_id_a`required	`string`
`contact_id_b`required	`string`
`match_type`required	`string`
`confidence_score`	`number \| null`
`status`required	`string`
`resolved_by`	`string \| null`
`resolved_at`	`string (date-time) \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`
`contact_a`	`ContactSummary \| null`	ContactSummary fields ContactSummary (not expanded)
`contact_b`	`ContactSummary \| null`	ContactSummary fields ContactSummary (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/duplicate-reviews/{review_id}

Get duplicate review

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`review_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_DuplicateReviewData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`DuplicateReviewData`	DuplicateReviewData fields DuplicateReviewData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/duplicate-reviews/{review_id}/dismiss

Dismiss duplicate pair

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`review_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonDuplicateReviewDismissBody

Field	Type	Description
`reason`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_DuplicateReviewData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`DuplicateReviewData`	DuplicateReviewData fields DuplicateReviewData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/duplicate-reviews/{review_id}/merge

Merge duplicate pair

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`review_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonDuplicateReviewMergeBody

Field	Type	Description
`surviving_contact_id`required	`string`
`field_resolutions`	`object \| null`

Responses

200Successful Response

application/jsonSuccessResponse_DuplicateReviewData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`DuplicateReviewData`	DuplicateReviewData fields DuplicateReviewData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/identity-reviews

List identity reviews

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`status`	query	`string \| null`
`business_contact_id`	query	`string (uuid) \| null`
`email_matched_consumer_id`	query	`string (uuid) \| null`
`phone_matched_consumer_id`	query	`string (uuid) \| null`
`created_after`	query	`string (date-time) \| null`
`created_before`	query	`string (date-time) \| null`
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_IdentityReviewData__

Field Type Description

request_idrequired string

success true default true

datarequired

IdentityReviewData[]

IdentityReviewData[] fields

Field	Type	Description
`id`required	`string`
`business_contact_id`required	`string`
`email_matched_consumer_id`	`string \| null`
`phone_matched_consumer_id`	`string \| null`
`conflict_snapshot`required	`object`
`status`required	`string`
`resolved_consumer_id`	`string \| null`
`resolution_action`	`string \| null`
`resolved_by`	`string \| null`
`resolved_at`	`string (date-time) \| null`
`notes`	`string \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`
`contact`	`ContactSummary \| null`	ContactSummary fields ContactSummary (not expanded)
`email_matched_consumer`	`ConsumerSummary \| null`	ConsumerSummary fields ConsumerSummary (not expanded)
`phone_matched_consumer`	`ConsumerSummary \| null`	ConsumerSummary fields ConsumerSummary (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/internal/businesses/{business_id}/identity-reviews/{review_id}

Get identity review

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`review_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_IdentityReviewData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`IdentityReviewData`	IdentityReviewData fields IdentityReviewData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/businesses/{business_id}/identity-reviews/{review_id}/resolve

Resolve identity review

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`review_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonIdentityReviewResolveBody

Field	Type	Description
`action`required	`enum`	one of "link_to_consumer", "merge_consumers_and_link", "create_new_consumer", "ignore"
`target_consumer_id`	`string \| null`
`notes`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_IdentityReviewData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`IdentityReviewData`	IdentityReviewData fields IdentityReviewData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.