Reference · 7 operations

Actions: contacts

Last updated from API version 2026-10-06 at 2026-10-23 19:43 UTC (live spec, refreshed hourly). openapi.json

actions.contacts.tag

Add tags to contacts.

post/api/v1/actions/contacts/tag

Scope: write
Credits: See the catalog entry
Idempotency-Key: required
Class: write
Approval floor: none
Runs: Inline for one target, else async
Targets: contact, contacts, rows
Max targets: 500
Dry run: Supported
Writes back: contact

Adds input.tags (1 to 20, at most 100 characters each) to each contact's tags; tags it already has are kept once. Write class: workspace data only, free, no approval. One contact runs inline (200 {data: {action, result}}), more (or mode: "async") create an async run (202). A contact with nothing to change is skipped UNCHANGED; a table row without a linked contact NO_CONTACT. dryRun: true returns who would change and writes nothing.

Parameters

Idempotency-Keyheaderstring
1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

min length 1max length 255
Owlbound-Dry-Runheaderboolean
true: same as body field dryRun: true (action operations).
Owlbound-Planheaderstring
A planId from a dry run: same as the body field planId (action operations). A different body planId is 400.

pattern ^plan_[0-9a-f]{48}$

Request body (required) · application/json

ContactsTagRequest

targetone ofrequired
0
+ Show child fields− Hide child fields
One of
ActionTargetContact
ActionTargetContacts
ActionTargetRows
inputobjectrequired
0
+ Show child fields− Hide child fields
- tagsarray of stringrequired
  min items 1max items 20
dryRunboolean
Same as the Owlbound-Dry-Run header.

0
planIdstring
Apply this dry run's plan (same as Owlbound-Plan). Not with dryRun: true.

pattern ^plan_[0-9a-f]{48}$
modestring
auto (default) runs inline when the operation is sync, one target would run and the class is not send; sync forces inline (422 ACTION_NOT_SYNC when it cannot); async forces a run.

autosyncasync
notifyActionNotify
Events for this action. targetEvents: true also writes one action.target.completed / action.target.failed event per target (feed and webhooks); without it only action-level events are written, to keep the volume down. webhook is accepted and has no effect (webhook endpoints subscribe by event type).

0

Responses

200

The finished action and its result (one target), or the dry-run plan.

Show schema

ActionRunResponse

dataone ofrequired
0
+ Show child fields− Hide child fields
One of
with action
actionActionrequired
One action run. Read it again with GET /api/v1/actions/{id}.

0
resultanyrequired
The target's result, or null when it was skipped or failed.

0
with plan
planPlanrequired
What a real call would do, from every check up to the first side effect. Nothing is reserved, sent, written or charged. The plan is stored for 15 minutes: send its planId with the real call to run exactly what was reviewed (409 PLAN_STALE with a new plan if anything bound changed or it expired).

0
metaResponseMetarequired
Metadata on every success response.

0

202

An async run was created (queued); poll it or read the event feed.

Show schema

ActionResponse

dataobjectrequired
0
+ Show child fields− Hide child fields
- actionActionrequired
  One action run. Read it again with GET /api/v1/actions/{id}.
  
  0
metaResponseMetarequired
Metadata on every success response.

0

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/actions/contacts/tag" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "kind": "contact",
    "contactId": "<contactId>"
  },
  "input": {
    "tags": [
      "<tags>"
    ]
  },
  "dryRun": true
}'

The example is a dry run: it returns a plan and runs, writes and charges nothing. See dry runs and plans.

actions.contacts.untag

Remove tags from contacts.

post/api/v1/actions/contacts/untag

Scope: write
Credits: See the catalog entry
Idempotency-Key: required
Class: write
Approval floor: none
Runs: Inline for one target, else async
Targets: contact, contacts, rows
Max targets: 500
Dry run: Supported
Writes back: contact

Removes input.tags from each contact's tags. Write class: workspace data only, free, no approval. One contact runs inline (200 {data: {action, result}}), more (or mode: "async") create an async run (202). A contact with nothing to change is skipped UNCHANGED; a table row without a linked contact NO_CONTACT. dryRun: true returns who would change and writes nothing.

Parameters

Idempotency-Keyheaderstring
1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

min length 1max length 255
Owlbound-Dry-Runheaderboolean
true: same as body field dryRun: true (action operations).
Owlbound-Planheaderstring
A planId from a dry run: same as the body field planId (action operations). A different body planId is 400.

pattern ^plan_[0-9a-f]{48}$

Request body (required) · application/json

ContactsTagRequest

targetone ofrequired
0
+ Show child fields− Hide child fields
One of
ActionTargetContact
ActionTargetContacts
ActionTargetRows
inputobjectrequired
0
+ Show child fields− Hide child fields
- tagsarray of stringrequired
  min items 1max items 20
dryRunboolean
Same as the Owlbound-Dry-Run header.

0
planIdstring
Apply this dry run's plan (same as Owlbound-Plan). Not with dryRun: true.

pattern ^plan_[0-9a-f]{48}$
modestring
auto (default) runs inline when the operation is sync, one target would run and the class is not send; sync forces inline (422 ACTION_NOT_SYNC when it cannot); async forces a run.

autosyncasync
notifyActionNotify
Events for this action. targetEvents: true also writes one action.target.completed / action.target.failed event per target (feed and webhooks); without it only action-level events are written, to keep the volume down. webhook is accepted and has no effect (webhook endpoints subscribe by event type).

0

Responses

200

The finished action and its result (one target), or the dry-run plan.

Show schema

ActionRunResponse

dataone ofrequired
0
+ Show child fields− Hide child fields
One of
with action
actionActionrequired
One action run. Read it again with GET /api/v1/actions/{id}.

0
resultanyrequired
The target's result, or null when it was skipped or failed.

0
with plan
planPlanrequired
What a real call would do, from every check up to the first side effect. Nothing is reserved, sent, written or charged. The plan is stored for 15 minutes: send its planId with the real call to run exactly what was reviewed (409 PLAN_STALE with a new plan if anything bound changed or it expired).

0
metaResponseMetarequired
Metadata on every success response.

0

202

An async run was created (queued); poll it or read the event feed.

Show schema

ActionResponse

dataobjectrequired
0
+ Show child fields− Hide child fields
- actionActionrequired
  One action run. Read it again with GET /api/v1/actions/{id}.
  
  0
metaResponseMetarequired
Metadata on every success response.

0

Errors

curl -X POST "https://app.owlbound.ai/api/v1/actions/contacts/untag" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "kind": "contact",
    "contactId": "<contactId>"
  },
  "input": {
    "tags": [
      "<tags>"
    ]
  },
  "dryRun": true
}'

The example is a dry run: it returns a plan and runs, writes and charges nothing. See dry runs and plans.

actions.contacts.set_status

Set contacts' status.

post/api/v1/actions/contacts/set_status

Scope: write
Credits: See the catalog entry
Idempotency-Key: required
Class: write
Approval floor: none
Runs: Inline for one target, else async
Targets: contact, contacts, rows
Max targets: 500
Dry run: Supported
Writes back: contact

Sets input.status (new, ready, incomplete, contacted, replied, converted, lost) on each contact. Write class: workspace data only, free, no approval. One contact runs inline (200 {data: {action, result}}), more (or mode: "async") create an async run (202). A contact with nothing to change is skipped UNCHANGED; a table row without a linked contact NO_CONTACT. dryRun: true returns who would change and writes nothing.

Parameters

Idempotency-Keyheaderstring
1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

min length 1max length 255
Owlbound-Dry-Runheaderboolean
true: same as body field dryRun: true (action operations).
Owlbound-Planheaderstring
A planId from a dry run: same as the body field planId (action operations). A different body planId is 400.

pattern ^plan_[0-9a-f]{48}$

Request body (required) · application/json

ContactsSetStatusRequest

targetone ofrequired
0
+ Show child fields− Hide child fields
One of
ActionTargetContact
ActionTargetContacts
ActionTargetRows
inputobjectrequired
0
+ Show child fields− Hide child fields
- statusstringrequired
  newreadyincompletecontactedrepliedconvertedlost
dryRunboolean
Same as the Owlbound-Dry-Run header.

0
planIdstring
Apply this dry run's plan (same as Owlbound-Plan). Not with dryRun: true.

pattern ^plan_[0-9a-f]{48}$
modestring
auto (default) runs inline when the operation is sync, one target would run and the class is not send; sync forces inline (422 ACTION_NOT_SYNC when it cannot); async forces a run.

autosyncasync
notifyActionNotify
Events for this action. targetEvents: true also writes one action.target.completed / action.target.failed event per target (feed and webhooks); without it only action-level events are written, to keep the volume down. webhook is accepted and has no effect (webhook endpoints subscribe by event type).

0

Responses

200

The finished action and its result (one target), or the dry-run plan.

Show schema

ActionRunResponse

dataone ofrequired
0
+ Show child fields− Hide child fields
One of
with action
actionActionrequired
One action run. Read it again with GET /api/v1/actions/{id}.

0
resultanyrequired
The target's result, or null when it was skipped or failed.

0
with plan
planPlanrequired
What a real call would do, from every check up to the first side effect. Nothing is reserved, sent, written or charged. The plan is stored for 15 minutes: send its planId with the real call to run exactly what was reviewed (409 PLAN_STALE with a new plan if anything bound changed or it expired).

0
metaResponseMetarequired
Metadata on every success response.

0

202

An async run was created (queued); poll it or read the event feed.

Show schema

ActionResponse

dataobjectrequired
0
+ Show child fields− Hide child fields
- actionActionrequired
  One action run. Read it again with GET /api/v1/actions/{id}.
  
  0
metaResponseMetarequired
Metadata on every success response.

0

Errors

curl -X POST "https://app.owlbound.ai/api/v1/actions/contacts/set_status" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "kind": "contact",
    "contactId": "<contactId>"
  },
  "input": {
    "status": "new"
  },
  "dryRun": true
}'

The example is a dry run: it returns a plan and runs, writes and charges nothing. See dry runs and plans.

actions.contacts.assign_owner

Assign contacts to an owner identity.

post/api/v1/actions/contacts/assign_owner

Scope: write
Credits: See the catalog entry
Idempotency-Key: required
Class: write
Approval floor: none
Runs: Inline for one target, else async
Targets: contact, contacts, rows
Max targets: 500
Dry run: Supported
Writes back: contact

Sets each contact's owner to input.ownerIdentityId, an identity of this workspace (another workspace's is 404), active and of a member of the workspace (else 403 IDENTITY_UNAVAILABLE). Write class: workspace data only, free, no approval. One contact runs inline (200 {data: {action, result}}), more (or mode: "async") create an async run (202). A contact with nothing to change is skipped UNCHANGED; a table row without a linked contact NO_CONTACT. dryRun: true returns who would change and writes nothing.

Parameters

Idempotency-Keyheaderstring
1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

min length 1max length 255
Owlbound-Dry-Runheaderboolean
true: same as body field dryRun: true (action operations).
Owlbound-Planheaderstring
A planId from a dry run: same as the body field planId (action operations). A different body planId is 400.

pattern ^plan_[0-9a-f]{48}$

Request body (required) · application/json

ContactsAssignOwnerRequest

targetone ofrequired
0
+ Show child fields− Hide child fields
One of
ActionTargetContact
ActionTargetContacts
ActionTargetRows
inputobjectrequired
0
+ Show child fields− Hide child fields
- ownerIdentityIdstringrequired
  An identity of this workspace.
  
  0
dryRunboolean
Same as the Owlbound-Dry-Run header.

0
planIdstring
Apply this dry run's plan (same as Owlbound-Plan). Not with dryRun: true.

pattern ^plan_[0-9a-f]{48}$
modestring
auto (default) runs inline when the operation is sync, one target would run and the class is not send; sync forces inline (422 ACTION_NOT_SYNC when it cannot); async forces a run.

autosyncasync
notifyActionNotify
Events for this action. targetEvents: true also writes one action.target.completed / action.target.failed event per target (feed and webhooks); without it only action-level events are written, to keep the volume down. webhook is accepted and has no effect (webhook endpoints subscribe by event type).

0

Responses

200

The finished action and its result (one target), or the dry-run plan.

Show schema

ActionRunResponse

dataone ofrequired
0
+ Show child fields− Hide child fields
One of
with action
actionActionrequired
One action run. Read it again with GET /api/v1/actions/{id}.

0
resultanyrequired
The target's result, or null when it was skipped or failed.

0
with plan
planPlanrequired
What a real call would do, from every check up to the first side effect. Nothing is reserved, sent, written or charged. The plan is stored for 15 minutes: send its planId with the real call to run exactly what was reviewed (409 PLAN_STALE with a new plan if anything bound changed or it expired).

0
metaResponseMetarequired
Metadata on every success response.

0

202

An async run was created (queued); poll it or read the event feed.

Show schema

ActionResponse

dataobjectrequired
0
+ Show child fields− Hide child fields
- actionActionrequired
  One action run. Read it again with GET /api/v1/actions/{id}.
  
  0
metaResponseMetarequired
Metadata on every success response.

0

Errors

curl -X POST "https://app.owlbound.ai/api/v1/actions/contacts/assign_owner" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "kind": "contact",
    "contactId": "<contactId>"
  },
  "input": {
    "ownerIdentityId": "<ownerIdentityId>"
  },
  "dryRun": true
}'

The example is a dry run: it returns a plan and runs, writes and charges nothing. See dry runs and plans.

actions.contacts.set_fields

Set contact fields (fill empty by default).

post/api/v1/actions/contacts/set_fields

Scope: write
Credits: See the catalog entry
Idempotency-Key: required
Class: write
Approval floor: none
Runs: Inline for one target, else async
Targets: contact, contacts, rows
Max targets: 500
Dry run: Supported
Writes back: contact

Writes input.fields (firstName, lastName, title, headline, company, companyDomain, email, phone, linkedInUrl, location, industry, notes) on each contact: only fields that are empty unless input.onConflict: overwrite; an empty value never clears a field. LinkedIn URLs are normalized; a new LinkedIn URL clears the ids derived from the old profile (provider member id, Sales Navigator URL). Re-planned against the contact right before the write. Write class: workspace data only, free, no approval. One contact runs inline (200 {data: {action, result}}), more (or mode: "async") create an async run (202). A contact with nothing to change is skipped UNCHANGED; a table row without a linked contact NO_CONTACT. dryRun: true returns who would change and writes nothing.

Parameters

Idempotency-Keyheaderstring
1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

min length 1max length 255
Owlbound-Dry-Runheaderboolean
true: same as body field dryRun: true (action operations).
Owlbound-Planheaderstring
A planId from a dry run: same as the body field planId (action operations). A different body planId is 400.

pattern ^plan_[0-9a-f]{48}$

Request body (required) · application/json

ContactsSetFieldsRequest

targetone ofrequired
0
+ Show child fields− Hide child fields
One of
ActionTargetContact
ActionTargetContacts
ActionTargetRows
inputobjectrequired
0
+ Show child fields− Hide child fields
- fieldsobjectrequired
  0
  + Show child fields− Hide child fields
  firstNamestring
  max length 2000
  lastNamestring
  max length 2000
  titlestring
  max length 2000
  headlinestring
  max length 2000
  companystring
  max length 2000
  companyDomainstring
  max length 2000
  emailstring
  max length 2000
  phonestring
  max length 2000
  linkedInUrlstring
  max length 2000
  locationstring
  max length 2000
  industrystring
  max length 2000
  notesstring
  max length 2000
- onConflictstring
  fillEmpty (default): only empty fields are written.
  
  fillEmptyoverwrite
dryRunboolean
Same as the Owlbound-Dry-Run header.

0
planIdstring
Apply this dry run's plan (same as Owlbound-Plan). Not with dryRun: true.

pattern ^plan_[0-9a-f]{48}$
modestring
auto (default) runs inline when the operation is sync, one target would run and the class is not send; sync forces inline (422 ACTION_NOT_SYNC when it cannot); async forces a run.

autosyncasync
notifyActionNotify
Events for this action. targetEvents: true also writes one action.target.completed / action.target.failed event per target (feed and webhooks); without it only action-level events are written, to keep the volume down. webhook is accepted and has no effect (webhook endpoints subscribe by event type).

0

Responses

200

The finished action and its result (one target), or the dry-run plan.

Show schema

ActionRunResponse

dataone ofrequired
0
+ Show child fields− Hide child fields
One of
with action
actionActionrequired
One action run. Read it again with GET /api/v1/actions/{id}.

0
resultanyrequired
The target's result, or null when it was skipped or failed.

0
with plan
planPlanrequired
What a real call would do, from every check up to the first side effect. Nothing is reserved, sent, written or charged. The plan is stored for 15 minutes: send its planId with the real call to run exactly what was reviewed (409 PLAN_STALE with a new plan if anything bound changed or it expired).

0
metaResponseMetarequired
Metadata on every success response.

0

202

An async run was created (queued); poll it or read the event feed.

Show schema

ActionResponse

dataobjectrequired
0
+ Show child fields− Hide child fields
- actionActionrequired
  One action run. Read it again with GET /api/v1/actions/{id}.
  
  0
metaResponseMetarequired
Metadata on every success response.

0

Errors

curl -X POST "https://app.owlbound.ai/api/v1/actions/contacts/set_fields" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "kind": "contact",
    "contactId": "<contactId>"
  },
  "input": {
    "fields": {
      "firstName": "<firstName>",
      "lastName": "<lastName>",
      "title": "<title>"
    }
  },
  "dryRun": true
}'

The example is a dry run: it returns a plan and runs, writes and charges nothing. See dry runs and plans.

actions.contacts.link_icp

Link contacts to an audience (ICP).

post/api/v1/actions/contacts/link_icp

Scope: write
Credits: See the catalog entry
Idempotency-Key: required
Class: write
Approval floor: none
Runs: Inline for one target, else async
Targets: contact, contacts, rows
Max targets: 500
Dry run: Supported
Writes back: contact

Sets each contact's audience to input.icpProfileId, an audience of this workspace (another workspace's is 404). Write class: workspace data only, free, no approval. One contact runs inline (200 {data: {action, result}}), more (or mode: "async") create an async run (202). A contact with nothing to change is skipped UNCHANGED; a table row without a linked contact NO_CONTACT. dryRun: true returns who would change and writes nothing.

Parameters

Idempotency-Keyheaderstring
1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

min length 1max length 255
Owlbound-Dry-Runheaderboolean
true: same as body field dryRun: true (action operations).
Owlbound-Planheaderstring
A planId from a dry run: same as the body field planId (action operations). A different body planId is 400.

pattern ^plan_[0-9a-f]{48}$

Request body (required) · application/json

ContactsLinkIcpRequest

targetone ofrequired
0
+ Show child fields− Hide child fields
One of
ActionTargetContact
ActionTargetContacts
ActionTargetRows
inputobjectrequired
0
+ Show child fields− Hide child fields
- icpProfileIdstringrequired
  An audience (ICP profile) of this workspace.
  
  0
dryRunboolean
Same as the Owlbound-Dry-Run header.

0
planIdstring
Apply this dry run's plan (same as Owlbound-Plan). Not with dryRun: true.

pattern ^plan_[0-9a-f]{48}$
modestring
auto (default) runs inline when the operation is sync, one target would run and the class is not send; sync forces inline (422 ACTION_NOT_SYNC when it cannot); async forces a run.

autosyncasync
notifyActionNotify
Events for this action. targetEvents: true also writes one action.target.completed / action.target.failed event per target (feed and webhooks); without it only action-level events are written, to keep the volume down. webhook is accepted and has no effect (webhook endpoints subscribe by event type).

0

Responses

200

The finished action and its result (one target), or the dry-run plan.

Show schema

ActionRunResponse

dataone ofrequired
0
+ Show child fields− Hide child fields
One of
with action
actionActionrequired
One action run. Read it again with GET /api/v1/actions/{id}.

0
resultanyrequired
The target's result, or null when it was skipped or failed.

0
with plan
planPlanrequired
What a real call would do, from every check up to the first side effect. Nothing is reserved, sent, written or charged. The plan is stored for 15 minutes: send its planId with the real call to run exactly what was reviewed (409 PLAN_STALE with a new plan if anything bound changed or it expired).

0
metaResponseMetarequired
Metadata on every success response.

0

202

An async run was created (queued); poll it or read the event feed.

Show schema

ActionResponse

dataobjectrequired
0
+ Show child fields− Hide child fields
- actionActionrequired
  One action run. Read it again with GET /api/v1/actions/{id}.
  
  0
metaResponseMetarequired
Metadata on every success response.

0

Errors

curl -X POST "https://app.owlbound.ai/api/v1/actions/contacts/link_icp" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "kind": "contact",
    "contactId": "<contactId>"
  },
  "input": {
    "icpProfileId": "<icpProfileId>"
  },
  "dryRun": true
}'

The example is a dry run: it returns a plan and runs, writes and charges nothing. See dry runs and plans.

actions.contacts.archive

Archive contacts (soft).

post/api/v1/actions/contacts/archive

Scope: write
Credits: See the catalog entry
Idempotency-Key: required
Class: write
Approval floor: none
Runs: Inline for one target, else async
Targets: contact, contacts, rows
Max targets: 500
Dry run: Supported
Writes back: contact

Archives each contact the way the app does (isArchived; it is then suppressed from outreach). Nothing is deleted. Write class: workspace data only, free, no approval. One contact runs inline (200 {data: {action, result}}), more (or mode: "async") create an async run (202). A contact with nothing to change is skipped UNCHANGED; a table row without a linked contact NO_CONTACT. dryRun: true returns who would change and writes nothing.

Parameters

Idempotency-Keyheaderstring
1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

min length 1max length 255
Owlbound-Dry-Runheaderboolean
true: same as body field dryRun: true (action operations).
Owlbound-Planheaderstring
A planId from a dry run: same as the body field planId (action operations). A different body planId is 400.

pattern ^plan_[0-9a-f]{48}$

Request body (required) · application/json

ContactsArchiveRequest

targetone ofrequired
0
+ Show child fields− Hide child fields
One of
ActionTargetContact
ActionTargetContacts
ActionTargetRows
inputobject
0
dryRunboolean
Same as the Owlbound-Dry-Run header.

0
planIdstring
Apply this dry run's plan (same as Owlbound-Plan). Not with dryRun: true.

pattern ^plan_[0-9a-f]{48}$
modestring
auto (default) runs inline when the operation is sync, one target would run and the class is not send; sync forces inline (422 ACTION_NOT_SYNC when it cannot); async forces a run.

autosyncasync
notifyActionNotify
Events for this action. targetEvents: true also writes one action.target.completed / action.target.failed event per target (feed and webhooks); without it only action-level events are written, to keep the volume down. webhook is accepted and has no effect (webhook endpoints subscribe by event type).

0

Responses

200

The finished action and its result (one target), or the dry-run plan.

Show schema

ActionRunResponse

dataone ofrequired
0
+ Show child fields− Hide child fields
One of
with action
actionActionrequired
One action run. Read it again with GET /api/v1/actions/{id}.

0
resultanyrequired
The target's result, or null when it was skipped or failed.

0
with plan
planPlanrequired
What a real call would do, from every check up to the first side effect. Nothing is reserved, sent, written or charged. The plan is stored for 15 minutes: send its planId with the real call to run exactly what was reviewed (409 PLAN_STALE with a new plan if anything bound changed or it expired).

0
metaResponseMetarequired
Metadata on every success response.

0

202

An async run was created (queued); poll it or read the event feed.

Show schema

ActionResponse

dataobjectrequired
0
+ Show child fields− Hide child fields
- actionActionrequired
  One action run. Read it again with GET /api/v1/actions/{id}.
  
  0
metaResponseMetarequired
Metadata on every success response.

0

Errors

curl -X POST "https://app.owlbound.ai/api/v1/actions/contacts/archive" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "kind": "contact",
    "contactId": "<contactId>"
  },
  "dryRun": true
}'

The example is a dry run: it returns a plan and runs, writes and charges nothing. See dry runs and plans.

Models on this page

Shared objects the operations above link to. Clients must ignore fields they do not know.

ActionTargetContactobject

kind"contact"required
0
contactIdstringrequired
0

ActionTargetContactsobject

kind"contacts"required
0
contactIdsarray of stringrequired
Deduplicated, order kept.

min items 1max items 1000

ActionTargetRowsobject

Rows of one table; each row's linked contact is the subject. A row without a linked contact is skipped NO_CONTACT (push it to contacts first); two rows of one contact act once (DUPLICATE_TARGET). Not available yet for some workspaces: the call answers 409 TABLE_STORE_UNSUPPORTED.

kind"rows"required
0
tableIdstringrequired
0
rowIdsarray of stringrequired
Deduplicated, order kept.

min items 1max items 1000

ActionNotifyobject

Events for this action. targetEvents: true also writes one action.target.completed / action.target.failed event per target (feed and webhooks); without it only action-level events are written, to keep the volume down. webhook is accepted and has no effect (webhook endpoints subscribe by event type).

targetEventsboolean
default false
webhookboolean
0

Actionobject

One action run. Read it again with GET /api/v1/actions/{id}.

idstringrequired
0
kindstringrequired
The operation id.

0
classstringrequired
Safety class: decides scope, approval, caps and enforcement.

readwritespendexternal_writesend
statusstringrequired
pending_approvalqueuedrunningsucceededfailedrejectedcanceledexpiredpartial
identityIdstring | nullrequired
0
approvalActionApproval | nullrequired
0
costobjectrequired
0
+ Show child fields− Hide child fields
- estimatednumberrequired
  0
- chargednumberrequired
  0
- reservationIdstring | nullrequired
  0
countsActionCountsrequired
0
targetobjectrequired
0
+ Show child fields− Hide child fields
- kindstringrequired
  0
- tableIdstring
  0
- viewIdstring
  0
- columnIdstring
  The send column this action runs (tables.rows.push target column).
  
  0
outputobject | nullrequired
0
resultanyrequired
The single target's result (sync), or null; bulk results are per target.

0
errorActionErrorrequired
0
actorActionActorrequired
Who started the action. agent is an LLM-driven caller (the in-app agent, MCP) acting for the key or member in onBehalfOf.

0
createdAtnumberrequired
0
updatedAtnumberrequired
0

ActionApprovalobject

modestringrequired
nonealwaysover_threshold
urlstring | nullrequired
0
decidedBystring | nullrequired
0
decidedAtnumber | nullrequired
0
expiresAtnumber | nullrequired
0

ActionCountsobject

totalintegerrequired
0
queuedintegerrequired
0
scheduledintegerrequired
0
runningintegerrequired
0
succeededintegerrequired
0
skippedintegerrequired
0
failedintegerrequired
0
canceledintegerrequired
0

ActionErrorobject

codestringrequired
0
messagestringrequired
0

ActionActorobject

Who started the action. agent is an LLM-driven caller (the in-app agent, MCP) acting for the key or member in onBehalfOf.

kindstringrequired
apiKeysessionagentjob
idstringrequired
API key id, user id, agent run id or job id.

0
onBehalfOfobject
Agent only.

0
+ Show child fields− Hide child fields
- kindstringrequired
  apiKeysession
- idstringrequired
  0

Planobject

What a real call would do, from every check up to the first side effect. Nothing is reserved, sent, written or charged. The plan is stored for 15 minutes: send its planId with the real call to run exactly what was reviewed (409 PLAN_STALE with a new plan if anything bound changed or it expired).

operationIdstringrequired
0
classstringrequired
Safety class: decides scope, approval, caps and enforcement.

readwritespendexternal_writesend
identityIdstring | nullrequired
0
targetsobjectrequired
0
+ Show child fields− Hide child fields
- totalintegerrequired
  0
- wouldRunintegerrequired
  0
- wouldSkiparray of objectrequired
  0
  + Show child fields− Hide child fields
  reasonstringrequired
  0
  countintegerrequired
  0
  samplearray of stringrequired
  0
creditsobjectrequired
0
+ Show child fields− Hide child fields
- estimatedMinnumberrequired
  0
- estimatedMaxnumberrequired
  0
- availablenumberrequired
  0
- capRemainingnumber | nullrequired
  0
quotaobject | nullrequired
LinkedIn sends: the daily budget the action spends (an estimate: warm-up, health and the identity's other sends move it; the send gate decides at send time). bucket is the daily limit's key, identityRemainingToday what the identity's account has left today, keyRemainingToday the key's, user's or agent's daily sends left (null: uncapped), wouldDefer the targets that would wait for a later day, firstSlotAt / lastSlotAt when the first and last of them would go (ms; null past 7 days). Null for other operations.

0
+ Show child fields− Hide child fields
- bucketstringrequired
  0
- identityRemainingTodaynumberrequired
  0
- keyRemainingTodaynumber | nullrequired
  0
- wouldDefernumberrequired
  0
- firstSlotAtnumber | nullrequired
  0
- lastSlotAtnumber | nullrequired
  0
approvalobjectrequired
0
+ Show child fields− Hide child fields
- requiredbooleanrequired
  0
- reasonstring | nullrequired
  key_modeoperation_floorover_thresholdagentrequestedidentity_owner
writesobjectrequired
0
previewarray of anyrequired
The first targets that would run (at most 5).

0
planIdstringrequired
Valid until expiresAt, for the principal that made the dry run only.

pattern ^plan_[0-9a-f]{48}$
expiresAtnumberrequired
When the plan expires (epoch milliseconds).

0

ResponseMetaobject

Metadata on every success response.

requestIdstringrequired
0
creditsCreditsMetarequired
0
pagePageMeta
Cursor pagination. hasMore is the only end signal; pages may be short.

0
dryRunboolean
True only on a dry-run response (action operations).

0

CreditsMetaobject

usednumberrequired
Credits charged by this request. Reads are free.

0
balancenumber
0
estimatednumber
Dry run only (action operations).

0
availablenumber
Dry run only (action operations).

0
reservationIdstring | null
Async operations only; the job settles this reservation.

0

PageMetaobject

Cursor pagination. hasMore is the only end signal; pages may be short.

nextCursorstring | nullrequired
0
hasMorebooleanrequired
0
limitintegerrequired
min 1max 200

← All operations