Skip to content
Ratify

Ratify API (1)

The public API (v1): push roster changes from an HRIS with a script, and pull people, immigration statuses, tracked dates, matters, deadlines, and attention items into your own reports.

Authenticate every request with an API key an Owner or Admin creates in Settings → Integrations: Authorization: Bearer ik_live_…. A READ key reads; a READ_WRITE_PEOPLE key also adds people and changes their employment fields. Keys never reach documents, notes, dependents, members, billing, or settings. The API is server to server: it takes no cookies and sends no CORS headers.

Dates are as recorded by HR or counsel. The API doesn't determine anyone's legal status or which date governs a status; direct legal questions to the organization's immigration counsel.

Each key may make 60 requests a minute (bursts of 20); past that, requests get 429 with Retry-After. Every request is recorded in the organization's audit log. Errors use the Problem shape. Within v1, changes are additive only.

People

Employees with immigration needs, their employment, statuses, and tracked dates.

List people

People who aren't deleted, sorted by name, 50 a page; archived people only with include_archived. Pass next_cursor back as cursor for the next page.

Authorizations:

bearerAuth

query Parameters

employment_status
string (EmploymentStatus)
Enum: "ACTIVE" "ON_LEAVE" "PENDING_START" "TERMINATED"

Only people with this employment status.

updated_since
string <date-time>

Only people whose employment, profile, statuses, or tracked dates changed at or after this time.

include_archived
boolean
Default: false

Include archived people (former employees).

cursor
string <= 1000 characters

The previous page's next_cursor.

Responses

Response Schema: application/json

required
Array of objects (PersonSummary) <= 50 items
Array (<= 50 items)
id
required
string <uuid>
display_name
required
string <= 300 characters
employee_number
string <= 64 characters
work_email
string <= 320 characters
job_title
string <= 200 characters
department
string <= 200 characters
work_location
string <= 200 characters
employment_status
required
string (EmploymentStatus)
Enum: "ACTIVE" "ON_LEAVE" "PENDING_START" "TERMINATED"
archived
required
boolean
required
Array of objects (StatusRef) <= 50 items
Array (<= 50 items)
category_key
required
string <= 100 characters
category_label
required
string <= 200 characters
object (NextExpiration)

The person's earliest tracked date on a current status or the person.

key_date_id
required
string <uuid>
kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
updated_at
required
string <date-time>

The last change to the person's employment, profile, statuses, or tracked dates.

next_cursor
string <= 1000 characters

Absent on the last page.

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "display_name": "string",
      • "employee_number": "string",
      • "work_email": "string",
      • "job_title": "string",
      • "department": "string",
      • "work_location": "string",
      • "employment_status": "ACTIVE",
      • "archived": true,
      • "current_statuses": [
        • {
          • "category_key": "string",
          • "category_label": "string"
          }
        ],
      • "next_expiration": {
        • "key_date_id": "21062c28-9286-4efb-88a6-c93393ec9c76",
        • "kind_key": "string",
        • "label": "string",
        • "date": "2019-08-24"
        },
      • "updated_at": "2019-08-24T14:15:22Z"
      }
    ],
  • "next_cursor": "string"
}

Add a person

Adds a person with their employment and profile fields, and optionally their current immigration status with its dates and person-level dates such as a passport's expiration. Needs a READ_WRITE_PEOPLE key. Follows the app's rules: field validation, unique employee numbers and work emails, the free Starter plan's tracked-employee limit (402), and a read-only organization's refusal (409). Send an Idempotency-Key to retry safely: the same key with the same body within 24 hours returns the person it created instead of adding another; the same key with a different body is refused (409 idempotency_key_reused).

Authorizations:

bearerAuth

header Parameters

Idempotency-Key
string [ 1 .. 255 ] characters

1 to 255 visible ASCII characters, such as a UUID, unique per request you mean to make once.

Request Body schema: application/json
required

employee_number
string <= 64 characters
work_email
string <= 320 characters
legal_first_name
required
string <= 100 characters
legal_middle_name
string <= 100 characters
legal_last_name
required
string <= 100 characters
preferred_name
string <= 100 characters
personal_email
string <= 320 characters

Saved for HR; the API doesn't return it.

phone
string <= 40 characters

Saved for HR; the API doesn't return it.

date_of_birth
string <date>

Saved for HR; the API doesn't return it.

country_of_birth
string <= 2 characters

Two-letter country code. Saved for HR; the API doesn't return it.

citizenship_country
string <= 2 characters

Two-letter country code. Saved for HR; the API doesn't return it.

job_title
string <= 200 characters
department
string <= 200 characters
manager_name
string <= 200 characters
manager_email
string <= 320 characters
work_location
string <= 200 characters
employment_status
string (EmploymentStatus)
Enum: "ACTIVE" "ON_LEAVE" "PENDING_START" "TERMINATED"
employment_start_date
string <date>
employment_end_date
string <date>
object (StatusInput)
category_key
required
string <= 100 characters

The immigration category, such as H1B (Settings → Lists).

valid_from
string <date>
state
string
Enum: "CURRENT" "PENDING"

CURRENT if absent.

Array of objects (KeyDateInput) <= 20 items

Dates on the status above.

Array (<= 20 items)
kind_key
required
string <= 100 characters

The kind of date, such as I94_ADMIT_UNTIL or PASSPORT_EXPIRES (Settings → Lists).

custom_label
string <= 200 characters

The date's name, for kind CUSTOM.

date
required
string <date>
source
string
Enum: "HR_ENTERED" "COUNSEL_PROVIDED" "IMPORTED"

Who it came from; HR_ENTERED if absent (COUNSEL_PROVIDED for MAX_STAY_DATE).

tracked
boolean

Whether it counts for deadlines and attention; true if absent.

Array of objects (KeyDateInput) <= 20 items

Person-level dates, such as a passport's expiration.

Array (<= 20 items)
kind_key
required
string <= 100 characters

The kind of date, such as I94_ADMIT_UNTIL or PASSPORT_EXPIRES (Settings → Lists).

custom_label
string <= 200 characters

The date's name, for kind CUSTOM.

date
required
string <date>
source
string
Enum: "HR_ENTERED" "COUNSEL_PROVIDED" "IMPORTED"

Who it came from; HR_ENTERED if absent (COUNSEL_PROVIDED for MAX_STAY_DATE).

tracked
boolean

Whether it counts for deadlines and attention; true if absent.

Responses

Response Schema: application/json

id
required
string <uuid>
employee_number
string <= 64 characters
work_email
string <= 320 characters
legal_first_name
required
string <= 100 characters
legal_last_name
required
string <= 100 characters
preferred_name
string <= 100 characters
display_name
required
string <= 300 characters
job_title
string <= 200 characters
department
string <= 200 characters
manager_name
string <= 200 characters
manager_email
string <= 320 characters
work_location
string <= 200 characters
employment_status
required
string (EmploymentStatus)
Enum: "ACTIVE" "ON_LEAVE" "PENDING_START" "TERMINATED"
employment_start_date
string <date>
employment_end_date
string <date>
archived
required
boolean
required
Array of objects (Status) <= 50 items
Array (<= 50 items)
id
required
string <uuid>
category_key
required
string <= 100 characters
category_label
required
string <= 200 characters
state
required
string
Value: "CURRENT"
valid_from
string <date>
needs_review
required
boolean

HR marked the status for review, for example after an import.

required
Array of objects (KeyDate) <= 500 items

Tracked dates on the current statuses and the person, as recorded. Several dates can apply to a status; confirm with counsel which one governs.

Array (<= 500 items)
id
required
string <uuid>
status_id
string <uuid>

The status it belongs to; absent for a person-level date.

kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
source
required
string
Enum: "HR_ENTERED" "COUNSEL_PROVIDED" "IMPORTED" "FROM_DOCUMENT"

Who recorded it.

object (NextExpiration)

The person's earliest tracked date on a current status or the person.

key_date_id
required
string <uuid>
kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
created_at
required
string <date-time>
updated_at
required
string <date-time>

Request samples

Content type
application/json
{
  • "employee_number": "string",
  • "work_email": "string",
  • "legal_first_name": "string",
  • "legal_middle_name": "string",
  • "legal_last_name": "string",
  • "preferred_name": "string",
  • "personal_email": "string",
  • "phone": "string",
  • "date_of_birth": "2019-08-24",
  • "country_of_birth": "st",
  • "citizenship_country": "st",
  • "job_title": "string",
  • "department": "string",
  • "manager_name": "string",
  • "manager_email": "string",
  • "work_location": "string",
  • "employment_status": "ACTIVE",
  • "employment_start_date": "2019-08-24",
  • "employment_end_date": "2019-08-24",
  • "status": {
    • "category_key": "string",
    • "valid_from": "2019-08-24",
    • "state": "CURRENT"
    },
  • "status_dates": [
    • {
      • "kind_key": "string",
      • "custom_label": "string",
      • "date": "2019-08-24",
      • "source": "HR_ENTERED",
      • "tracked": true
      }
    ],
  • "person_dates": [
    • {
      • "kind_key": "string",
      • "custom_label": "string",
      • "date": "2019-08-24",
      • "source": "HR_ENTERED",
      • "tracked": true
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "employee_number": "string",
  • "work_email": "string",
  • "legal_first_name": "string",
  • "legal_last_name": "string",
  • "preferred_name": "string",
  • "display_name": "string",
  • "job_title": "string",
  • "department": "string",
  • "manager_name": "string",
  • "manager_email": "string",
  • "work_location": "string",
  • "employment_status": "ACTIVE",
  • "employment_start_date": "2019-08-24",
  • "employment_end_date": "2019-08-24",
  • "archived": true,
  • "current_statuses": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "category_key": "string",
      • "category_label": "string",
      • "state": "CURRENT",
      • "valid_from": "2019-08-24",
      • "needs_review": true
      }
    ],
  • "tracked_dates": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "status_id": "4e949624-bc0f-439e-a9f2-25a23938812c",
      • "kind_key": "string",
      • "label": "string",
      • "date": "2019-08-24",
      • "source": "HR_ENTERED"
      }
    ],
  • "next_expiration": {
    • "key_date_id": "21062c28-9286-4efb-88a6-c93393ec9c76",
    • "kind_key": "string",
    • "label": "string",
    • "date": "2019-08-24"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Find a person by an HRIS identifier

The person with this employee number, or this work email (not case-sensitive). Give exactly one. 404 when nobody has it.

Authorizations:

bearerAuth

query Parameters

employee_number
string <= 64 characters
work_email
string <= 320 characters

Responses

Response Schema: application/json

id
required
string <uuid>
employee_number
string <= 64 characters
work_email
string <= 320 characters
legal_first_name
required
string <= 100 characters
legal_last_name
required
string <= 100 characters
preferred_name
string <= 100 characters
display_name
required
string <= 300 characters
job_title
string <= 200 characters
department
string <= 200 characters
manager_name
string <= 200 characters
manager_email
string <= 320 characters
work_location
string <= 200 characters
employment_status
required
string (EmploymentStatus)
Enum: "ACTIVE" "ON_LEAVE" "PENDING_START" "TERMINATED"
employment_start_date
string <date>
employment_end_date
string <date>
archived
required
boolean
required
Array of objects (Status) <= 50 items
Array (<= 50 items)
id
required
string <uuid>
category_key
required
string <= 100 characters
category_label
required
string <= 200 characters
state
required
string
Value: "CURRENT"
valid_from
string <date>
needs_review
required
boolean

HR marked the status for review, for example after an import.

required
Array of objects (KeyDate) <= 500 items

Tracked dates on the current statuses and the person, as recorded. Several dates can apply to a status; confirm with counsel which one governs.

Array (<= 500 items)
id
required
string <uuid>
status_id
string <uuid>

The status it belongs to; absent for a person-level date.

kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
source
required
string
Enum: "HR_ENTERED" "COUNSEL_PROVIDED" "IMPORTED" "FROM_DOCUMENT"

Who recorded it.

object (NextExpiration)

The person's earliest tracked date on a current status or the person.

key_date_id
required
string <uuid>
kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
created_at
required
string <date-time>
updated_at
required
string <date-time>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "employee_number": "string",
  • "work_email": "string",
  • "legal_first_name": "string",
  • "legal_last_name": "string",
  • "preferred_name": "string",
  • "display_name": "string",
  • "job_title": "string",
  • "department": "string",
  • "manager_name": "string",
  • "manager_email": "string",
  • "work_location": "string",
  • "employment_status": "ACTIVE",
  • "employment_start_date": "2019-08-24",
  • "employment_end_date": "2019-08-24",
  • "archived": true,
  • "current_statuses": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "category_key": "string",
      • "category_label": "string",
      • "state": "CURRENT",
      • "valid_from": "2019-08-24",
      • "needs_review": true
      }
    ],
  • "tracked_dates": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "status_id": "4e949624-bc0f-439e-a9f2-25a23938812c",
      • "kind_key": "string",
      • "label": "string",
      • "date": "2019-08-24",
      • "source": "HR_ENTERED"
      }
    ],
  • "next_expiration": {
    • "key_date_id": "21062c28-9286-4efb-88a6-c93393ec9c76",
    • "kind_key": "string",
    • "label": "string",
    • "date": "2019-08-24"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a person

A person's employment fields, current immigration statuses, and tracked dates as recorded by HR or counsel. Several dates can apply to a status; confirm with counsel which one governs.

Authorizations:

bearerAuth

path Parameters

personId
required
string <uuid>

Responses

Response Schema: application/json

id
required
string <uuid>
employee_number
string <= 64 characters
work_email
string <= 320 characters
legal_first_name
required
string <= 100 characters
legal_last_name
required
string <= 100 characters
preferred_name
string <= 100 characters
display_name
required
string <= 300 characters
job_title
string <= 200 characters
department
string <= 200 characters
manager_name
string <= 200 characters
manager_email
string <= 320 characters
work_location
string <= 200 characters
employment_status
required
string (EmploymentStatus)
Enum: "ACTIVE" "ON_LEAVE" "PENDING_START" "TERMINATED"
employment_start_date
string <date>
employment_end_date
string <date>
archived
required
boolean
required
Array of objects (Status) <= 50 items
Array (<= 50 items)
id
required
string <uuid>
category_key
required
string <= 100 characters
category_label
required
string <= 200 characters
state
required
string
Value: "CURRENT"
valid_from
string <date>
needs_review
required
boolean

HR marked the status for review, for example after an import.

required
Array of objects (KeyDate) <= 500 items

Tracked dates on the current statuses and the person, as recorded. Several dates can apply to a status; confirm with counsel which one governs.

Array (<= 500 items)
id
required
string <uuid>
status_id
string <uuid>

The status it belongs to; absent for a person-level date.

kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
source
required
string
Enum: "HR_ENTERED" "COUNSEL_PROVIDED" "IMPORTED" "FROM_DOCUMENT"

Who recorded it.

object (NextExpiration)

The person's earliest tracked date on a current status or the person.

key_date_id
required
string <uuid>
kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
created_at
required
string <date-time>
updated_at
required
string <date-time>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "employee_number": "string",
  • "work_email": "string",
  • "legal_first_name": "string",
  • "legal_last_name": "string",
  • "preferred_name": "string",
  • "display_name": "string",
  • "job_title": "string",
  • "department": "string",
  • "manager_name": "string",
  • "manager_email": "string",
  • "work_location": "string",
  • "employment_status": "ACTIVE",
  • "employment_start_date": "2019-08-24",
  • "employment_end_date": "2019-08-24",
  • "archived": true,
  • "current_statuses": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "category_key": "string",
      • "category_label": "string",
      • "state": "CURRENT",
      • "valid_from": "2019-08-24",
      • "needs_review": true
      }
    ],
  • "tracked_dates": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "status_id": "4e949624-bc0f-439e-a9f2-25a23938812c",
      • "kind_key": "string",
      • "label": "string",
      • "date": "2019-08-24",
      • "source": "HR_ENTERED"
      }
    ],
  • "next_expiration": {
    • "key_date_id": "21062c28-9286-4efb-88a6-c93393ec9c76",
    • "kind_key": "string",
    • "label": "string",
    • "date": "2019-08-24"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change a person's employment fields

Changes only the fields sent: job title, department, manager, work location, employment status, and employment dates. Send null to clear a field. Needs a READ_WRITE_PEOPLE key, and follows the app's rules like createPerson.

Authorizations:

bearerAuth

path Parameters

personId
required
string <uuid>

Request Body schema: application/json
required

non-empty
job_title
string or null <= 200 characters
department
string or null <= 200 characters
manager_name
string or null <= 200 characters
manager_email
string or null <= 320 characters
work_location
string or null <= 200 characters
employment_status
string (EmploymentStatus)
Enum: "ACTIVE" "ON_LEAVE" "PENDING_START" "TERMINATED"
employment_start_date
string or null <date>
employment_end_date
string or null <date>

Responses

Response Schema: application/json

id
required
string <uuid>
employee_number
string <= 64 characters
work_email
string <= 320 characters
legal_first_name
required
string <= 100 characters
legal_last_name
required
string <= 100 characters
preferred_name
string <= 100 characters
display_name
required
string <= 300 characters
job_title
string <= 200 characters
department
string <= 200 characters
manager_name
string <= 200 characters
manager_email
string <= 320 characters
work_location
string <= 200 characters
employment_status
required
string (EmploymentStatus)
Enum: "ACTIVE" "ON_LEAVE" "PENDING_START" "TERMINATED"
employment_start_date
string <date>
employment_end_date
string <date>
archived
required
boolean
required
Array of objects (Status) <= 50 items
Array (<= 50 items)
id
required
string <uuid>
category_key
required
string <= 100 characters
category_label
required
string <= 200 characters
state
required
string
Value: "CURRENT"
valid_from
string <date>
needs_review
required
boolean

HR marked the status for review, for example after an import.

required
Array of objects (KeyDate) <= 500 items

Tracked dates on the current statuses and the person, as recorded. Several dates can apply to a status; confirm with counsel which one governs.

Array (<= 500 items)
id
required
string <uuid>
status_id
string <uuid>

The status it belongs to; absent for a person-level date.

kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
source
required
string
Enum: "HR_ENTERED" "COUNSEL_PROVIDED" "IMPORTED" "FROM_DOCUMENT"

Who recorded it.

object (NextExpiration)

The person's earliest tracked date on a current status or the person.

key_date_id
required
string <uuid>
kind_key
required
string <= 100 characters
label
required
string <= 200 characters
date
required
string <date>
created_at
required
string <date-time>
updated_at
required
string <date-time>

Request samples

Content type
application/json
{
  • "job_title": "string",
  • "department": "string",
  • "manager_name": "string",
  • "manager_email": "string",
  • "work_location": "string",
  • "employment_status": "ACTIVE",
  • "employment_start_date": "2019-08-24",
  • "employment_end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "employee_number": "string",
  • "work_email": "string",
  • "legal_first_name": "string",
  • "legal_last_name": "string",
  • "preferred_name": "string",
  • "display_name": "string",
  • "job_title": "string",
  • "department": "string",
  • "manager_name": "string",
  • "manager_email": "string",
  • "work_location": "string",
  • "employment_status": "ACTIVE",
  • "employment_start_date": "2019-08-24",
  • "employment_end_date": "2019-08-24",
  • "archived": true,
  • "current_statuses": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "category_key": "string",
      • "category_label": "string",
      • "state": "CURRENT",
      • "valid_from": "2019-08-24",
      • "needs_review": true
      }
    ],
  • "tracked_dates": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "status_id": "4e949624-bc0f-439e-a9f2-25a23938812c",
      • "kind_key": "string",
      • "label": "string",
      • "date": "2019-08-24",
      • "source": "HR_ENTERED"
      }
    ],
  • "next_expiration": {
    • "key_date_id": "21062c28-9286-4efb-88a6-c93393ec9c76",
    • "kind_key": "string",
    • "label": "string",
    • "date": "2019-08-24"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Matters

Immigration matters and where each one stands.

List matters

Immigration matters, newest first, 50 a page, with their lifecycle, who they're waiting on, whether they're blocked, and their dates. Pass next_cursor back as cursor for the next page.

Authorizations:

bearerAuth

query Parameters

person_id
string <uuid>

Only this person's matters.

lifecycle
Array of strings (MatterLifecycle) <= 8 items
Items Enum: "DRAFT" "ACTIVE" "FILED" "APPROVED" "DENIED" "WITHDRAWN" "CLOSED" "CANCELLED"

Only matters in these lifecycle states.

waiting_on
string (WaitingOn)
Enum: "NONE" "EMPLOYER" "EMPLOYEE" "COUNSEL"
blocked
boolean
cursor
string <= 1000 characters

The previous page's next_cursor.

Responses

Response Schema: application/json

required
Array of objects (Matter) <= 50 items
Array (<= 50 items)
id
required
string <uuid>
person_id
required
string <uuid>
person_name
required
string <= 300 characters
matter_type_key
required
string <= 100 characters
matter_type_label
required
string <= 200 characters
title
required
string <= 300 characters
lifecycle
required
string (MatterLifecycle)
Enum: "DRAFT" "ACTIVE" "FILED" "APPROVED" "DENIED" "WITHDRAWN" "CLOSED" "CANCELLED"
waiting_on
required
string (WaitingOn)
Enum: "NONE" "EMPLOYER" "EMPLOYEE" "COUNSEL"
blocked
required
boolean
opened_on
required
string <date>
target_filing_date
string <date>
filed_on
string <date>
receipt_on
string <date>

When the receipt arrived (getMatter only).

decision_on
string <date>
closed_at
string <date-time>

getMatter only.

updated_at
required
string <date-time>
next_cursor
string <= 1000 characters

Absent on the last page.

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
      • "person_name": "string",
      • "matter_type_key": "string",
      • "matter_type_label": "string",
      • "title": "string",
      • "lifecycle": "DRAFT",
      • "waiting_on": "NONE",
      • "blocked": true,
      • "opened_on": "2019-08-24",
      • "target_filing_date": "2019-08-24",
      • "filed_on": "2019-08-24",
      • "receipt_on": "2019-08-24",
      • "decision_on": "2019-08-24",
      • "closed_at": "2019-08-24T14:15:22Z",
      • "updated_at": "2019-08-24T14:15:22Z"
      }
    ],
  • "next_cursor": "string"
}

Get a matter

Authorizations:

bearerAuth

path Parameters

matterId
required
string <uuid>

Responses

Response Schema: application/json

id
required
string <uuid>
person_id
required
string <uuid>
person_name
required
string <= 300 characters
matter_type_key
required
string <= 100 characters
matter_type_label
required
string <= 200 characters
title
required
string <= 300 characters
lifecycle
required
string (MatterLifecycle)
Enum: "DRAFT" "ACTIVE" "FILED" "APPROVED" "DENIED" "WITHDRAWN" "CLOSED" "CANCELLED"
waiting_on
required
string (WaitingOn)
Enum: "NONE" "EMPLOYER" "EMPLOYEE" "COUNSEL"
blocked
required
boolean
opened_on
required
string <date>
target_filing_date
string <date>
filed_on
string <date>
receipt_on
string <date>

When the receipt arrived (getMatter only).

decision_on
string <date>
closed_at
string <date-time>

getMatter only.

updated_at
required
string <date-time>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
  • "person_name": "string",
  • "matter_type_key": "string",
  • "matter_type_label": "string",
  • "title": "string",
  • "lifecycle": "DRAFT",
  • "waiting_on": "NONE",
  • "blocked": true,
  • "opened_on": "2019-08-24",
  • "target_filing_date": "2019-08-24",
  • "filed_on": "2019-08-24",
  • "receipt_on": "2019-08-24",
  • "decision_on": "2019-08-24",
  • "closed_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Dates and attention

Upcoming deadlines and what needs attention now.

Upcoming deadlines

Tracked dates, active matters' target filing dates, and open tasks' due dates from today (the organization's date) through within_days days ahead, soonest first, at most 1,000. Dates are as recorded by HR or counsel; this doesn't determine anyone's legal status.

Authorizations:

bearerAuth

query Parameters

within_days
integer [ 1 .. 365 ]
Default: 90

How many days ahead to look.

Responses

Response Schema: application/json

today
required
string <date>

The organization's date.

through
required
string <date>

The last day looked at.

required
Array of objects (Deadline) <= 1000 items
Array (<= 1000 items)
id
required
string <uuid>

The key date's or task's ID, or the matter's for a target filing date.

type
required
string
Enum: "KEY_DATE" "TARGET_FILING" "TASK_DUE"

KEY_DATE (a tracked date on a status or the person), TARGET_FILING (an active matter's target filing date), or TASK_DUE (an open task's due date).

date
required
string <date>
days_until
required
integer
label
required
string <= 300 characters
kind_key
string <= 100 characters

The key date's kind (KEY_DATE only).

person_id
required
string <uuid>
person_name
required
string <= 300 characters
matter_id
string <uuid>
matter_label
string <= 200 characters
truncated
required
boolean

True when there were more than 1,000; ask for fewer days.

Response samples

Content type
application/json
{
  • "today": "2019-08-24",
  • "through": "2019-08-24",
  • "data": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "KEY_DATE",
      • "date": "2019-08-24",
      • "days_until": 0,
      • "label": "string",
      • "kind_key": "string",
      • "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
      • "person_name": "string",
      • "matter_id": "511398d3-f899-487a-b5e9-081dfd79cc32",
      • "matter_label": "string"
      }
    ],
  • "truncated": true
}

What needs attention

The attention items the app's dashboard shows now, most urgent first: tracked dates coming up, matters waiting on someone, overdue tasks. Snoozed and handled items are left out.

Authorizations:

bearerAuth

Responses

Response Schema: application/json

today
required
string <date>

The organization's date.

required
Array of objects (AttentionItem) <= 5000 items
Array (<= 5000 items)
rule_id
required
string <= 20 characters
severity
required
string
Enum: "CRITICAL" "HIGH" "MEDIUM"
title
required
string <= 500 characters
detail
string <= 1000 characters
due_on
string <date>
days_until
integer
person_id
string <uuid>
subject_type
required
string
Enum: "key_date" "status" "person" "matter" "task" "document_request" "document"

What it's about.

subject_id
string <uuid>

The subject's ID, for a key date, status, person, matter, or task.

action
required
string <= 200 characters

What to do next, in words.

url
required
string <= 2000 characters

Where to do it in the app (sign-in needed).

Response samples

Content type
application/json
{
  • "today": "2019-08-24",
  • "data": [
    • {
      • "rule_id": "string",
      • "severity": "CRITICAL",
      • "title": "string",
      • "detail": "string",
      • "due_on": "2019-08-24",
      • "days_until": 0,
      • "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
      • "subject_type": "key_date",
      • "subject_id": "80e197be-61ad-4068-b4ff-a483fb5c18f9",
      • "action": "string",
      • "url": "string"
      }
    ]
}