Companies

Where people work.

On this page

List companies
Get a company
Rename a company
Delete a company

List companies

GET/companies

The companies people's positions name. Companies are created from positions, so there's no POST; one that no position names any more is deleted (it appears in /deletions as a company).

curl "$NIFTY_URL/api/v1/companies" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Query parameters

Name	Description
`order`name \| id \| updated_at · optional	`name` sorts ignoring case and accents, like the web, with `id` as the tie-breaker.
`direction`asc \| desc · optional	`asc` (ascending) or `desc` (descending), for `order`.
`updated_since`date-time · optional	Only records updated at or after this time (ISO 8601 with `Z` or a UTC offset), ordered by `updated_at, id`.
`cursor`string · optional	`meta.next_cursor` from the previous page.
`limit`integer · optional	Items per page, up to 100; a larger number is taken as 100.
`count`true \| false · optional	`true` adds `meta.total_count`: the size of the filtered set (with `updated_since` too), ignoring `cursor` and `limit`. Anything but `true` or `false` is a 400.

Response

200 OK Errors: 400 401 429

{
  "data": [
    {
      "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "name": "Northwind",
      "created_at": "2026-10-10T09:30:00Z",
      "updated_at": "2026-10-10T09:30:00Z"
    }
  ],
  "meta": {
    "next_cursor": "eyJrIjpbIjIwMjYtMTAtMDlUMDg6MzA6MDBaIl19",
    "limit": 1,
    "total_count": 1
  }
}

Get a company

GET/companies/{id}

curl "$NIFTY_URL/api/v1/companies/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

Name	Description
`id`ULID	A record's ID.

Response

200 OK Errors: 401 404 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "name": "Northwind",
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Rename a company

PATCH/companies/{id}

Also PUT /companies/{id}, the same.

A name another company has, ignoring case, is a 422 (name: "already exists"); there's no merge. Changing only the casing is fine. People at the company aren't changed: their positions hold only company_id.

curl -X PATCH "$NIFTY_URL/api/v1/companies/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company":{"name":"Northwind"}}'

Path parameters

Name	Description
`id`ULID	A record's ID.

Request body

Name	Description
`company`object
`company.name`string · optional	Spaces are squished. Unique ignoring case.

Response

200 OK Errors: 400 401 403 404 415 422 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "name": "Northwind",
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Delete a company

DELETE/companies/{id}

Permanent. Writes a company deletion record. Positions with a title lose the company; a position with only this company is deleted (a position deletion record). The people whose positions changed, deleted ones included, get a new updated_at.

curl -X DELETE "$NIFTY_URL/api/v1/companies/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

Name	Description
`id`ULID	A record's ID.

Response

204 Deleted Errors: 401 403 404 429