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

If repayment accounts per User are enabled on your account, an SCA_ENROLLMENT requirement is also created for each User. See SCA enrollment.

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.

SCA_ENROLLMENT is the exception: it is ACCEPTED only when every eligible party is accepted.

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.

🚧

Static portal links are being phased out. The url returned in resolutionMethods (and the deprecated Onboarding.portalUrl) does not expire today, but expiring links will become the only supported behavior. Migrate to POST /companies/{companyId}/requirements/portal-link now — see Getting a fresh portal link below. Timeline will be tracked in Upcoming breaking changes.

Getting a fresh portal link

POST /companies/{companyId}/requirements/portal-link returns a portal link for a given target, same as resolutionMethods[].url where type is portal — except this one is short-lived and expires.

Because it expires, don't request it ahead of time and store it next to your user's data. Request it at the moment your user needs to be redirected, then immediately redirect them to the returned url:

1. On your own platform, show a "Complete verification" link or button that does not embed any portal URL yet.
2. When your user clicks it, call the endpoint with the relevant targetType / targetId.
3. Redirect the user to the url from the response right away, before it expires.

POST /companies/{companyId}/requirements/portal-link

{
  "targetType": "User",
  "targetId": "string",
  "returnUrl": "https://app.example.com/suppliers/42"
}

returnUrl is optional. Pass an absolute https URL and the portal sends your user back to it once every requirement is complete, so they land back on your platform instead of on a dead end. Any other scheme, or a relative URL, returns a 400.

returnUrl only takes effect once the requirement portal is enabled on your account. Until then, the endpoint accepts it but ignores it, so contact your Aria account manager before relying on it.

{
  "url": "https://portal.example.com/case/abc",
  "expiresAt": "2026-11-03T10:00:00.000Z"
}

expiresAt is the latest time the link can be opened. The link works once, so it stops working earlier when your user opens it. It is null until the requirement portal is enabled on your account: the link then comes from the identity verification provider, and Aria does not control its expiry.

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"
}

SCA enrollment

When a User has its own repayment account, the money its debtors pay lands in an account held in the User's name at our payment provider. To move money out of that account, for example to pay the User what remains after its Loans are repaid, European payment rules (PSD2) require Strong Customer Authentication (SCA) from the person who controls it. The SCA_ENROLLMENT requirement tracks that step.

Until it is ACCEPTED, the payment provider refuses payments out of the User's repayment account.

How it works

1. The requirement is created with the User, with no eligible party yet.
2. The User opens the portal and chooses which legal representative enrolls. This choice is final.
3. Aria opens the payout account for that person. You receive requirement.eligible-party.created.
4. On the portal, the representative enrolls with the payment provider and gives consent for transfers.
5. The eligible party moves to ACCEPTED, and you receive requirement.eligible-party.updated and requirement.updated.

Send the User to the portal with Getting a fresh portal link. This requirement cannot be completed through the API: its eligible parties have no api resolution method, and the submit endpoint does not apply.

Renewal

The payment provider can ask for a new enrollment at any time, or the representative can withdraw consent. The eligible party then goes back from ACCEPTED to PENDING or REFUSED, and payments out of the account stop until the representative enrolls again on the portal. Listen to requirement.updated to catch this.

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"
      }
    ]
  }
}