Data fields

List data fields

Lists all data fields available to the API client: the builtin catalog (identified by stable keys; prompts are never included) and the client's custom data fields (identified by uuid; includes the authored prompt). Reference them from template data-field items.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Query Parameters

limit?integer

Maximum number of items to return. Values above 100 are clamped to 100.

Range1 <= value <= 100

Default50

cursor?string

Opaque pagination cursor from the previous page's next_cursor.

Response Body

`application/json`

curl -X GET "https://example.com/v1/data_fields"

{  "data": [    {      "id": "string",      "key": "anrede",      "builtin": true,      "display_name": "string",      "category": "personal",      "prompt": "string",      "value_format": "currency",      "archived": true,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Create a custom data field

Creates a custom data field. The prompt is the partner-authored extraction instruction; value_format constrains the extracted value's unit and shape.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Request Body

application/json

The data field's attributes, including the authored prompt.

TypeScript Definitions

Use the request body type in TypeScript.

Attributes for a new custom data field.

display_name*string

Human-readable name.

Length1 <= length <= 200

prompt*string

The extraction instruction. Describe the value, where it appears in the documents, and which candidate to pick when several match.

Length1 <= length <= 8000

category?DefinitionCategory

Topical category. Defaults to other.

Value in

"personal"
"employment"
"financial"
"loan"
"property"
"other"

value_format?|

Unit and shape constraint for the extracted value. Defaults to free text.

Response Body

`application/json`

curl -X POST "https://example.com/v1/data_fields" \  -H "Content-Type: application/json" \  -d '{    "display_name": "string",    "prompt": "string"  }'

{  "id": "string",  "key": "anrede",  "builtin": true,  "display_name": "string",  "category": "personal",  "prompt": "string",  "value_format": "currency",  "archived": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Get a data field

Returns one data field, builtin (never includes a prompt) or custom.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Path Parameters

data_field_id*string

The data field's id — a builtin data-field key or a custom uuid.

Response Body

`application/json`

curl -X GET "https://example.com/v1/data_fields/string"

{  "id": "string",  "key": "anrede",  "builtin": true,  "display_name": "string",  "category": "personal",  "prompt": "string",  "value_format": "currency",  "archived": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Update a custom data field

Updates a custom data field. The change is versioned internally: the id stays stable, templates referencing it use the new version for future submissions, and past extraction results keep the version they ran with. Builtin data fields cannot be updated (422 invalid_field).

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Path Parameters

data_field_id*string

The data field's id — a builtin data-field key or a custom uuid.

Request Body

application/json

The attributes to change.

TypeScript Definitions

Use the request body type in TypeScript.

Custom data field changes; omitted fields stay unchanged.

display_name?string

New name.

Length1 <= length <= 200

prompt?string

New extraction instruction.

Length1 <= length <= 8000

category?DefinitionCategory

New topical category.

Value in

"personal"
"employment"
"financial"
"loan"
"property"
"other"

value_format?|

New unit and shape constraint, or null for free text.

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/data_fields/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "key": "anrede",  "builtin": true,  "display_name": "string",  "category": "personal",  "prompt": "string",  "value_format": "currency",  "archived": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Archive a custom data field

Archives a custom data field: it disappears from listings and can no longer be added to templates. Templates and past results already referencing it keep working. Builtin data fields cannot be archived (422 invalid_field).

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Path Parameters

data_field_id*string

The data field's id — a builtin data-field key or a custom uuid.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/data_fields/string"

Empty

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

200application/json

400application/json

401application/json

403application/json

429application/json

defaultapplication/json

201application/json

400application/json

401application/json

403application/json

422application/json

429application/json

defaultapplication/json

200application/json

401application/json

403application/json

404application/json

429application/json

defaultapplication/json

200application/json

400application/json

401application/json

403application/json

404application/json

422application/json

429application/json

defaultapplication/json

204

401application/json

403application/json

404application/json

422application/json

429application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`