Tags

List your tags

Every tag you currently offer, newest first. Retired tags are not listed, though they still appear on the verifications that carry them. Cursor-paginated, newest first. limit accepts 1 to 100 and defaults to 20. To walk further, set starting_after to the id of the last record on the page you just read. has_more tells you another page exists and next_cursor is the value to pass back; on the last page has_more is false and next_cursor is null. An unknown cursor is ignored and you get the first page. Requires the verification:read permission on the calling key.

Authorization

secretKey

AuthorizationBearer <token>

Secret API key, server-side only. Example: Bearer TWK_...

In: header

Query Parameters

limit?integer

How many records to return. 1 to 100, defaults to 20.

Range1 <= value <= 100

Default20

starting_after?string

A tag id; returns the page after it.

Match^tag_

Response Body

`application/json`

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

{  "object": "list",  "data": [    {      "id": "string",      "object": "tag",      "name": "string",      "slug": "string",      "color": "slate",      "description": "string",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

Create a tag

Author a new tag. Names are matched on a normalised form, so "High Risk" and "high-risk" are the same tag: if the name you send already resolves to one of your live tags you get that tag back with 200 rather than an error, which means a script can call this without checking first.

Requires the verification:create permission on the calling key, the same write capability that starts a verification.

Authorization

secretKey

AuthorizationBearer <token>

Secret API key, server-side only. Example: Bearer TWK_...

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length <= 48

color?TagColor

A named swatch rather than a colour value, so a tag stays readable in both the light and dark console themes.

Value in

"slate"
"blue"
"green"
"amber"
"red"
"purple"

description?|

Lengthlength <= 200

Response Body

`application/json`

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

{  "id": "string",  "object": "tag",  "name": "string",  "slug": "string",  "color": "slate",  "description": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Update a tag

Change a tag's name, colour or description. Every field is optional and only what you send is changed.

A RENAME IS RETROACTIVE: the new name shows on every verification already carrying this tag, including decisions you have already sent to applicants. Requires the verification:create permission.

Authorization

secretKey

AuthorizationBearer <token>

Secret API key, server-side only. Example: Bearer TWK_...

In: header

Path Parameters

id*string

The tag id.

Match^tag_

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Every field optional. Only what you send is changed.

name?string

Length1 <= length <= 48

color?TagColor

A named swatch rather than a colour value, so a tag stays readable in both the light and dark console themes.

Value in

"slate"
"blue"
"green"
"amber"
"red"
"purple"

description?|

Lengthlength <= 200

Response Body

`application/json`

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

{  "id": "string",  "object": "tag",  "name": "string",  "slug": "string",  "color": "slate",  "description": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Retire a tag

Stop offering a tag. It is NOT erased: every verification and applicant already carrying it keeps showing the label, because a decision you took months ago has to keep meaning what it meant. The name becomes available to create again.

Requires the verification:create permission.

Authorization

secretKey

AuthorizationBearer <token>

Secret API key, server-side only. Example: Bearer TWK_...

In: header

Path Parameters

id*string

The tag id.

Match^tag_

Response Body

`application/json`

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

{  "id": "string",  "object": "tag",  "name": "string",  "slug": "string",  "color": "slate",  "description": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "retired": true}

Tag a verification

Put one or more of your labels on a verification, whether a reviewer decided it or the engine did. Send tags with ids you already have, names to resolve or create by name, or both.

Applying a tag that is already there is a no-op rather than an error, so this is safe to retry. The response is the full set now on the verification. Ids that are not yours, or that name a retired tag, are ignored rather than failing the whole call; compare the response against what you sent.

Requires the verification:create permission.

Authorization

secretKey

AuthorizationBearer <token>

Secret API key, server-side only. Example: Bearer TWK_...

In: header

Path Parameters

id*string

The verification session id.

Match^vs_

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Send at least one of tags or names.

tags?array<>

Ids of tags you already have.

Itemsitems <= 25

names?array<>

Names to resolve by their normalised form, creating the tag if none of yours matches. This is the half that makes tagging usable straight from a risk rule: you can say what you mean without first looking up whether the tag exists.

Itemsitems <= 25

Response Body

`application/json`

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

{  "object": "list",  "data": [    {      "id": "string",      "name": "string",      "color": "slate"    }  ],  "has_more": true,  "next_cursor": "string"}

Remove a tag from a verification

Requires the verification:create permission.

Authorization

secretKey

AuthorizationBearer <token>

Secret API key, server-side only. Example: Bearer TWK_...

In: header

Path Parameters

id*string

The verification session id.

Match^vs_

tagId*string

The tag id.

Match^tag_

Response Body

`application/json`

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

{  "id": "string",  "object": "tag",  "removed": true}

Tag an applicant

Put labels on the PERSON rather than on one attempt. A tag here is waiting on them the next time they start a verification with you, which is what makes it different from tagging a verification.

Note that an applicant record is created once a face has been matched, so a recent verification may not have one yet.

Requires the verification:create permission.

Authorization

secretKey

AuthorizationBearer <token>

Secret API key, server-side only. Example: Bearer TWK_...

In: header

Path Parameters

id*string

The applicant id.

Match^app_

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Send at least one of tags or names.

tags?array<>

Ids of tags you already have.

Itemsitems <= 25

names?array<>

Itemsitems <= 25

Response Body

`application/json`

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

{  "object": "list",  "data": [    {      "id": "string",      "name": "string",      "color": "slate"    }  ],  "has_more": true,  "next_cursor": "string"}

Remove a tag from an applicant

Requires the verification:create permission.

Authorization

secretKey

AuthorizationBearer <token>

Secret API key, server-side only. Example: Bearer TWK_...

In: header

Path Parameters

id*string

The applicant id.

Match^app_

tagId*string

The tag id.

Match^tag_

Response Body

`application/json`

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

{  "id": "string",  "object": "tag",  "removed": true}

200application/json

400application/json

401application/json

403application/json

429application/json

503application/json

200application/json

201application/json

400application/json

401application/json

403application/json

429application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

503application/json

200application/json

401application/json

403application/json

404application/json

429application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

503application/json

200application/json

401application/json

403application/json

404application/json

429application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

503application/json

200application/json

401application/json

403application/json

404application/json

429application/json

503application/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`

`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`