Suggestions

People a document names, for the owner to link or dismiss.

On this page

List suggestions
Dismiss a suggestion
Undo dismissing a suggestion

List suggestions

GET/suggestions

A document's suggestions (source_type=document&source_id=), newest first. By default only pending ones from a live document (a deleted one's come back with it if it's restored). status=all also lists accepted and declined ones. source_type and source_id are required, except when syncing with updated_since, which lists every document's, decided ones too.

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

Query parameters

Name	Description
`status`pending \| all · optional
`source_type`document · optional	With `source_id`, only that document's.
`source_id`ULID · optional	A record's ID.
`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",
      "kind": "person",
      "status": "pending",
      "source": {
        "type": "document",
        "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
        "title": "string"
      },
      "title": "Ada Lovelace",
      "person": {
        "person_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
        "person_name": "string",
        "email": "[email protected]"
      },
      "result_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "decided_at": "2026-10-10T09:30:00Z",
      "created_at": "2026-10-10T09:30:00Z",
      "updated_at": "2026-10-10T09:30:00Z"
    }
  ],
  "meta": {
    "next_cursor": "eyJrIjpbIjIwMjYtMTAtMDlUMDg6MzA6MDBaIl19",
    "limit": 1,
    "total_count": 1
  }
}

Dismiss a suggestion

POST/suggestions/{id}/decline

Hides a pending suggestion for good; it's never suggested again. Undo within 10 seconds with POST /suggestions/{id}/restore. Declining a declined one changes nothing; an accepted one is a 422. No body.

curl -X POST "$NIFTY_URL/api/v1/suggestions/01j9zq3k8m5x2v7c4n6b0t1r9e/decline" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

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

Headers

Name	Description
`Idempotency-Key`string · optional	Makes a POST safe to retry for 24 hours. Needs a bearer token (`400` under session auth).

Response

200 OK Errors: 400 401 403 404 409 415 422 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "kind": "person",
    "status": "pending",
    "source": {
      "type": "document",
      "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "title": "string"
    },
    "title": "Ada Lovelace",
    "person": {
      "person_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "person_name": "string",
      "email": "[email protected]"
    },
    "result_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "decided_at": "2026-10-10T09:30:00Z",
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Undo dismissing a suggestion

POST/suggestions/{id}/restore

Within 10 seconds of declining it, the suggestion is pending again. A pending one is returned unchanged (a retry is safe). Past the 10 seconds, accepted, unknown, or its person deleted or linked to the document since: a 404. No body.

curl -X POST "$NIFTY_URL/api/v1/suggestions/01j9zq3k8m5x2v7c4n6b0t1r9e/restore" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

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

Headers

Name	Description
`Idempotency-Key`string · optional	Makes a POST safe to retry for 24 hours. Needs a bearer token (`400` under session auth).

Response

200 OK Errors: 400 401 403 404 409 415 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "kind": "person",
    "status": "pending",
    "source": {
      "type": "document",
      "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "title": "string"
    },
    "title": "Ada Lovelace",
    "person": {
      "person_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "person_name": "string",
      "email": "[email protected]"
    },
    "result_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "decided_at": "2026-10-10T09:30:00Z",
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}