Document requests API

Ask a lead for documents with a link — no sign-in needed.

Module code lead_documents · 7 actions · 3 data models · 6 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: lead_documents (everything), lead_documents:read (read only) or lead_documents:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

lead_documents.issue_link

Ask a lead for documents — Opens a files upload link for one lead (as the platform, so a rep needs no Files permission) and ties it to the documents it asks for.

Needs lead_documents:write · changes data

• Canonical address: POST /api/v1/actions/lead_documents.issue_link

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: lead_documents.link_issued

What it writes: lead_document_link (insert) — Ties the link to the lead and retires the previous one

curl -X POST https://app.getera.io/api/v1/lead_document_links/actions/issue_link \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"leadId":"LEAD_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "lead_documents.link_issued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.leadDocumentLinks.issueLink({
  leadId: "LEAD_ID"
})

era lead_document_links issue_link \
  --lead-id "LEAD_ID"

{
  "name": "era__lead_documents__issue_link",
  "arguments": {
    "leadId": "LEAD_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold lead_documents:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 lead_not_found, lead_archived, no_requests, request_not_available, upload_link_not_open, upload_link_taken · 429 slow down

lead_documents.renew_link

Give a lead’s document link more time — Moves the expiry of the link a lead was sent, keeping the address they already have.

Needs lead_documents:write · changes data

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: lead_documents.link_renewed

curl -X POST https://app.getera.io/api/v1/actions/lead_documents.renew_link \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"leadId":"LEAD_ID","days":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "lead_documents.link_renewed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("lead_documents.renew_link", {
  leadId: "LEAD_ID",
  days: 1
})

era run lead_documents.renew_link \
  --lead-id "LEAD_ID" \
  --days 1

{
  "name": "era__lead_documents__renew_link",
  "arguments": {
    "leadId": "LEAD_ID",
    "days": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold lead_documents:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 lead_not_found, lead_archived, no_open_link · 429 slow down

lead_documents.review

Accept or reject a document — Records a decision about what was sent; a rejection tells the person why.

Needs lead_documents:write · changes data

• Canonical address: POST /api/v1/actions/lead_documents.review

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: lead_documents.reviewed

What it writes: lead_document (update) — Records the decision

curl -X POST https://app.getera.io/api/v1/lead_documents/LEAD_DOCUMENT_ID/actions/review \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"decision":"accepted"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "lead_documents.reviewed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.leadDocuments.review("LEAD_DOCUMENT_ID", {
  decision: "accepted"
})

era lead_documents review LEAD_DOCUMENT_ID \
  --decision "accepted"

{
  "name": "era__lead_documents__review",
  "arguments": {
    "id": "LEAD_DOCUMENT_ID",
    "decision": "accepted"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold lead_documents:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_in_that_state, reason_required · 429 slow down

lead_documents.revoke_link

Close a lead’s document link — Stops the link a lead was sent from working. What they already sent stays.

Needs lead_documents:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/lead_documents.revoke_link

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: lead_documents.link_revoked

What it writes: lead_document_link (update) — Retires the join; files closes the link

curl -X POST https://app.getera.io/api/v1/lead_document_links/actions/revoke_link \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"leadId":"LEAD_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "lead_documents.link_revoked"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.leadDocumentLinks.revokeLink({
  leadId: "LEAD_ID"
})

era lead_document_links revoke_link \
  --lead-id "LEAD_ID"

{
  "name": "era__lead_documents__revoke_link",
  "arguments": {
    "leadId": "LEAD_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold lead_documents:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 lead_not_found, lead_archived, no_open_link · 429 slow down

lead_documents.set_request

Add or change a document request — What the business asks a lead to send — a passport, a diploma — and what files it accepts.

Needs lead_documents:manage · changes data

• Canonical address: POST /api/v1/actions/lead_documents.set_request

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: lead_documents.request_changed

What it writes: lead_document_request (upsert) — Writes the request

curl -X POST https://app.getera.io/api/v1/lead_document_requests/LEAD_DOCUMENT_REQUEST_ID/actions/set_request \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "lead_documents.request_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.leadDocumentRequests.setRequest("LEAD_DOCUMENT_REQUEST_ID", {
  name: "Name"
})

era lead_document_requests set_request LEAD_DOCUMENT_REQUEST_ID \
  --name "Name"

{
  "name": "era__lead_documents__set_request",
  "arguments": {
    "id": "LEAD_DOCUMENT_REQUEST_ID",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold lead_documents:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, name_taken · 429 slow down

lead_documents.set_request_active

Open or close a document request — Stops asking for a document without touching what was already sent.

Needs lead_documents:manage · changes data

• Canonical address: POST /api/v1/actions/lead_documents.set_request_active

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: lead_documents.request_changed

What it writes: lead_document_request (update) — Opens or closes it

curl -X POST https://app.getera.io/api/v1/lead_document_requests/LEAD_DOCUMENT_REQUEST_ID/actions/set_request_active \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"active":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "lead_documents.request_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.leadDocumentRequests.setRequestActive("LEAD_DOCUMENT_REQUEST_ID", {
  active: true
})

era lead_document_requests set_request_active LEAD_DOCUMENT_REQUEST_ID \
  --active true

{
  "name": "era__lead_documents__set_request_active",
  "arguments": {
    "id": "LEAD_DOCUMENT_REQUEST_ID",
    "active": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold lead_documents:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_in_that_state · 429 slow down

lead_documents.submit

File a document a lead sent — Attaches an uploaded file to the lead, against the document it was sent for.

Needs lead_documents:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/lead_documents.submit

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: lead_documents.submitted

What it writes: lead_document (insert) — Files the document; lead_document_link (update) — Stamps when the link was last used

curl -X POST https://app.getera.io/api/v1/lead_documents/actions/submit \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"token":"Link token","requestId":"LEAD_DOCUMENT_REQUEST_ID","fileId":"FILE_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "lead_documents.submitted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.leadDocuments.submit({
  token: "Link token",
  requestId: "LEAD_DOCUMENT_REQUEST_ID",
  fileId: "FILE_ID"
})

era lead_documents submit \
  --token "Link token" \
  --request-id "LEAD_DOCUMENT_REQUEST_ID" \
  --file-id "FILE_ID"

{
  "name": "era__lead_documents__submit",
  "arguments": {
    "token": "Link token",
    "requestId": "LEAD_DOCUMENT_REQUEST_ID",
    "fileId": "FILE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold lead_documents:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 link_unknown, link_expired, request_not_on_link, file_not_found · 429 slow down

Data models

LeadDocumentLink

Table lead_document_link · Resource lead_document_links

• GET /api/v1/lead_document_links
• GET /api/v1/lead_document_links/{id}

Primary key: id

LeadDocumentRequest

Table lead_document_request · Resource lead_document_requests

• GET /api/v1/lead_document_requests
• GET /api/v1/lead_document_requests/{id}

Primary key: id

Checks:

• CHECK ((max_file_size_mb > 0))

LeadDocument

Table lead_document · Resource lead_documents

• GET /api/v1/lead_documents
• GET /api/v1/lead_documents/{id}

Primary key: id

Events

Workflows and webhooks react to these events.