Requirements

Requirements represent checks that Aria may ask you to complete for a User or a Debtor. They notify you when an action is needed (such as verifying an identity or collecting a document) and track the progress of that check through one or more eligible parties.

When are requirements created?

For Users

Requirements are automatically created for a User upon creation whenuser.canBeInvoiceOwner is true

For Debtors

A LIVENESS requirement may be created at Debtor creation time for specific clients. If this applies to your integration, Aria will reach out in advance.

📘

Note: If no requirement is returned by our API, no action is needed for this counterparty.

Recommended flow

1. Subscribe to requirement.created, requirement.updated, requirement.eligible-party.created and requirement.eligible-party.updated webhooks.
2. Create a User or a Debtor.
3. Get notified via webhook when a requirement is created, along with its eligible-parties.
4. Complete the requirement via the API or the portal.
5. Get notified via requirement.eligible-party.updated as each party's validationStatus changes, and via requirement.updated when the requirement's overall status changes.

Requirement types

* Some documents may briefly appear as required after creation but will be fetched and validated automatically.

Requirement status

A requirement's status is aggregated by Aria across all its eligible parties (excluding waived ones), following an OR logic with this priority order: ACCEPTED > REFUSED > EXPIRED > IN_REVIEW > PENDING.

• PENDING — No submission has been made yet for any eligible party.
• IN_REVIEW — Aria is currently reviewing some submissions.
• EXPIRED — A previously accepted check has expired and must be renewed.
• REFUSED — One or more parties were rejected, and none are accepted or expired.
• ACCEPTED — At least one eligible party has been validated, regardless of the others.

Aria's internal teams can waive an eligible party when their check is no longer needed. Waived parties are excluded from the status calculation, which allows a requirement to reach ACCEPTED even if some parties were not accepted.

Resolution methods

Resolution methods indicate how a requirement can be fulfilled. For requirements with eligible parties (e.g. ID_DOCUMENT, LIVENESS), each EligibleParty carries its own resolutionMethods with a party-specific URL. For company-level requirements (e.g. COMPANY_INFORMATION, ARIA_VALIDATION), resolution methods are not applicable — the portal is accessed directly via the requirement's context.

Each resolution method has:

• portal — A hosted portal page specific to this party. Share the url with the relevant individual or redirect them directly.
• api — Submit documents directly via the API using the eligible party's id.

Eligible parties

Eligible parties are not embedded in the requirement object. Retrieve them separately via GET /companies/{companyId}/requirements/{requirementId}/eligible-parties. The requirement is satisfied as soon as one of them is validated (OR logic).

Each eligible party has:

• type — INDIVIDUAL or COMPANY.
• name — full name for an individual, company name for a company. May be null if not yet known.
• resolutionMethods — available channels to fulfill the requirement for this specific party.
• validationStatus — the status of the check for this specific party.
• refusalReasons — present when validationStatus is REFUSED.
• waived — when true, this party is excluded from the requirement's status calculation.
• respondedAt — date of Aria's last decision on this party. Null if no decision yet.
• lastSubmittedAt — date of the most recent submission. Null if no submission yet.

Eligible party validationStatus

• PENDING — No submission has been made yet for this party.
• IN_REVIEW — Aria is reviewing the submission.
• EXPIRED — A previously accepted check has expired and must be renewed.
• ACCEPTED — The check passed for this party.
• REFUSED — The submission was rejected. See refusalReasons for details.

Submissions can only be sent when validationStatus is PENDING, REFUSED, or EXPIRED.

Submitting documents

To submit documents for an eligible party, send a POST request with the file IDs:

POST /companies/{companyId}/requirements/{requirementId}/eligible-parties/{eligiblePartyId}/submit

{
  "frontSideFileId": "uuid",
  "backSideFileId": "uuid"
}

The endpoint returns 201 with a submittedAt timestamp. The party's validationStatus will be updated asynchronously once the submission is processed — subscribe to requirement.eligible-party.updated to be notified.

{
  "submittedAt": "2026-04-02T10:00:00.000Z"
}

Webhooks

Subscribe to these events to be notified when data changes:

Webhook payloads

{
  "date": "string",
  "event": "requirement.created",
  "payload": {
    "id": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "type": "ARIA_VALIDATION",
    "status": "PENDING",
    "targetId": "string",
    "targetType": "User",
    "resolutionMethods": [
      {
        "type": "portal",
        "url": "string"
      }
    ]
  }
}

{
  "date": "string",
  "event": "requirement.eligible-party.updated",
  "payload": {
    "id": "string",
    "requirementId": "string",
    "type": "INDIVIDUAL",
    "name": "string",
    "validationStatus": "IN_REVIEW",
    "refusalReasons": [],
    "waived": false,
    "respondedAt": null,
    "lastSubmittedAt": "2026-04-02T10:00:00.000Z"
  }
}

{
  "date": "string",
  "event": "requirement.eligible-party.waived",
  "payload": {
    "id": "string",
    "requirementId": "string",
    "type": "INDIVIDUAL",
    "name": "string",
    "validationStatus": "PENDING",
    "refusalReasons": [],
    "waived": true,
    "respondedAt": null,
    "lastSubmittedAt": null
  }
}

{
  "date": "string",
  "event": "requirement.waived",
  "payload": {
    "id": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "type": "ARIA_VALIDATION",
    "status": "ACCEPTED",
    "targetId": "string",
    "targetType": "User",
    "resolutionMethods": [
      {
        "type": "portal",
        "url": "string"
      }
    ]
  }
}