Authorizations API

This API allows managing authorizations in the system. It provides endpoints to create, read, update, and delete authorizations, as well as to handle signatures and attachments associated with the authorizations.

The Authorization Object

The Authorization object represents an authorization in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenant": "tenant123",
  "formId": "form123",
  "key": "consent_form",
  "label": "Consent Form",
  "identityKey": "email",
  "identityValue": "user@example.com",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "expiresAt": "2028-01-01T00:00:00Z",
  "ipAddress": "192.168.1.1",
  "policyLink": "https://example.com/policy",
  "externalId": "ext123",
  "tags": ["important", "urgent"],
  "authorizedAt": "2023-01-01T12:00:00Z",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-02T12:00:00Z",
  "hasAttachments": true,
  "hasSignatures": true,
  "hasSignatureEvidences": true
}

Attributes

Signature Evidence

Signing an authorization leaves an evidence record on it, saying how it was signed and with what.

The records travel inside the Authorization object, in signatureEvidences, next to the hasSignatureEvidences flag. Anyone reading an authorization reads its evidence too, so treat it as you would any other personal data the object carries. They are also read by the public signature verification page, which compares the PDF against the stored hash and shows the evidence to whoever holds the signed file, and by Chat, on the authorization sheet.

evidenceType says which kind of record it is. An evidence saved before this field existed does not carry it, and is an OTP signature -- the only kind there was.

A record looks like this:

{
  "signatureId": "sig_9f2c1a",
  "tenant": "tenant123",
  "documentHash": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
  "hashAlgorithm": "SHA-256",
  "otpProvider": "sendgrid",
  "otpChannel": "email",
  "signatureType": "simple",
  "signedAt": "2026-09-08T15:04:05.481920+00:00",
  "channel": "web",
  "ip": "203.0.113.10",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/128.0",
  "device": "Win32 1920x1080",
  "timezone": "America/Mexico_City",
  "locale": "es-MX",
  "whatsappMessageId": null,
  "otpVerifiedFrom": { "ip": "203.0.113.10", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/128.0", "acceptLanguage": "es-MX,es;q=0.9", "timezone": "America/Mexico_City", "locale": "es-MX", "platform": "Win32", "screen": "1920x1080", "capturedAt": "2026-09-08T15:02:41.117204+00:00" },
  "signerIdentity": { "key": "email", "value": "user@example.com" },
  "consentVersion": null
}

Evidence Attributes

Context fields depend on the conversation channel. All of them are optional: a signature without context is recorded anyway, with those fields set to null.

The SAT authorization (web forms) appends records to the same list with a different shape: evidence_type: form_submission, channel, message_id, form_response_id and captured_at. The table above describes the AltScore OTP signature only.

IP, user agent and device are the customer's personal data. They are stored on the authorization and shown in Chat and on the public signature verification page to whoever holds the signed PDF. The tenant handles them under its own data policy.

Available Operations

Create a New Authorization

Creates a new authorization in the system.

POST /v1/authorizations

Input Parameters:

Example Request:

{
  "tenant": "tenant123",
  "key": "consent_form",
  "identityKey": "email",
  "identityValue": "user@example.com",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "policyLink": "https://example.com/policy",
  "tags": ["important", "urgent"]
}

Successful Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Retrieve an Authorization

Retrieves the information of a specific authorization.

GET /v1/authorizations/:authorization_id

Path Parameters:

Successful Response:

The response will be a complete Authorization object, as described above.

Delete an Authorization

Deletes an authorization from the system.

DELETE /v1/authorizations/:authorization_id

Path Parameters:

Successful Response:

Status code 204 (No Content) if the deletion was successful.

Sign an Authorization

Initiates the signing process of an authorization by sending an OTP.

POST /v1/authorizations/:authorization_id/signatures

Path Parameters:

Input Parameters:

Example Request:

{
  "value": "user@example.com",
  "contactMethod": "email",
  "templateId": "otp_template_1",
  "codeSize": 6,
  "expiresIn": 300,
  "maxAttempts": 3
}

Successful Response:

{
  "otpId": "otp123456"
}

Verify Authorization Signature

Verifies the OTP code to complete the signing of an authorization.

POST /v1/authorizations/:authorization_id/signatures/attempt

Path Parameters:

Input Parameters:

Example Request:

{
  "otpId": "otp123456",
  "code": "123456"
}

Successful Response:

Status code 202 (Accepted) if the verification was successful.

List Authorizations

Retrieves a paginated list of authorizations with filtering and sorting options.

GET /v1/authorizations

Query Parameters:

Successful Response:

The response will be a paginated list of Authorization objects.

Error Handling

The API may return the following error codes:

Errors will include a descriptive message in the response body.