Activate Light Tier KYC

Light tier KYC allows you to onboard individual users with minimal personal information and begin transacting immediately, up to a threshold. Activating light tier requires three steps: creating a compliance review, uploading the required attestations, and submitting the review for compliance evaluation.

Step 1: Create a compliance review

Create a compliance review for the light tier using the Create Compliance Review endpoint. The review is created in draft status and returns the list of attestations required before you can submit.

Example request

curl --request POST \
       --url https://api.muralpay.com/api/compliance/2b5a8c1d-3f4e-4a2b-9c7d-1e8f6a3b2c4d/reviews \
       --header 'accept: application/json' \
       --header 'authorization: Bearer $API-KEY' \
       --header 'content-type: application/json' \
       --data '{
         "tier": "light"
       }'

Example response

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tier": "light",
    "status": {
      "type": "draft"
    },
    "createdAt": "2026-03-03T12:00:00.000Z",
    "requiredAttestations": [
      { "type": "individualPersonalInfoLight" }
    ],
    "uploadedAttestations": []
  }

Save the id — you will need it for the next two steps.

Error Cases

409 — Active review already exists

Only one active (draft or inReview) compliance review may exist per organization per tier at a time. If you attempt to create a second, the request returns 409 Conflict. Retrieve the existing review using the List Compliance Reviews endpoint to continue where you left off.

  {
    "statusCode": 409,
    "message": "An active compliance review already exists for the light tier.",
    "error": "Conflict"
  }

Step 2: Upload attestations

Upload the required KYC data to the review using the Upload Attestations endpoint. You can re-upload the same type to correct a value before submitting.

Example request

  curl --request PUT \
       --url https://api.muralpay.com/api/compliance/2b5a8c1d-3f4e-4a2b-9c7d-1e8f6a3b2c4d/reviews/a1b2c3d4-e5f6-7890-abcd-ef1234567890/attestations \
       --header 'accept: application/json' \
       --header 'authorization: Bearer $API-KEY' \
       --header 'content-type: application/json' \
       --data '{
         "attestations": [
           {
             "type": "individualPersonalInfoLight",
             "name": {
               "firstName": "Jane",
               "lastName": "Doe"
             },
             "birthDate": "1990-01-15",
             "nationality": "US",
             "phoneNumber": "+14155551234",
             "residentialAddress": {
               "address1": "123 Main St",
               "city": "Austin",
               "subdivision": "TX",
               "postalCode": "78701",
               "country": "US"
             }
           }
         ]
       }'

Example response

 {
    "attestations": [
      {
        "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
        "type": "individualPersonalInfoLight",
        "createdAt": "2026-03-03T12:01:00.000Z"
      }
    ]
  }

Error Cases

400 — Invalid request body

Returned when the request body fails validation — for example, a missing required field or an incorrectly formatted value. The message array identifies the specific fields that need to be corrected.

  {
    "statusCode": 400,
    "message": [
      "birthDate must be a valid ISO 8601 date string",
      "nationality must be a valid ISO 3166-1 alpha-2 country code"
    ],
    "error": "Bad Request"
  }

404 — Review not found

Returned when the reviewId does not exist or does not belong to the specified organization.

  {
    "statusCode": 404,
    "message": "Compliance review not found.",
    "error": "Not Found"
  }

422 — Review is not in draft status

Attestations can only be uploaded while the review is in draft status. If the review has already been submitted, create a new review to retry.

  {
    "statusCode": 422,
    "message": "Review is not in draft status.",
    "error": "Unprocessable Entity"
  }

Step 3: Submit the review

Once all required attestations are uploaded, submit the review for compliance evaluation using the Submit Compliance Review endpoint. Mural validates that all required attestations are present, transitions the review to inReview, and queues it for evaluation.

Example request

  curl --request POST \
       --url https://api.muralpay.com/api/compliance/2b5a8c1d-3f4e-4a2b-9c7d-1e8f6a3b2c4d/reviews/a1b2c3d4-e5f6-7890-abcd-ef1234567890/submit \
       --header 'accept: application/json' \
       --header 'authorization: Bearer $API-KEY'

Example response

 {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tier": "light",
    "status": {
      "type": "inReview",
      "submittedAt": "2026-03-03T12:02:00.000Z"
    }
  }

If any required attestations are missing, this request returns 422 Unprocessable Entity with a list of which attestation types still need to be uploaded.

Error Cases

404 — Review not found

Returned when the reviewId does not exist or does not belong to the specified organization.

{
    "statusCode": 404,
    "message": "Compliance review not found.",
    "error": "Not Found"
  }

409 — Review is not in draft status

A review can only be submitted once. If the review has already been submitted or is no longer in draft status, this error is returned.

 {
    "statusCode": 409,
    "message": "Review is not in draft status.",
    "error": "Conflict"
  }

422 — Missing required attestations

Returned when one or more required attestation types have not yet been uploaded to the review. The response body identifies exactly which attestation types are still needed and which have already been uploaded.

 {
    "errorInstanceId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "name": "MissingAttestationsException",
    "message": "Required attestations are missing for the light tier compliance review.",
    "params": {
      "reviewId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tier": "light",
      "requiredAttestations": [
        { "type": "individualPersonalInfoLight" }
      ],
      "uploadedAttestations": []
    }
  }

Step 4: Await the compliance decision

Once submitted, the review is evaluated asynchronously. Mural will notify you of the outcome via webhook. You can also poll the review status at any time using the Get Compliance Review endpoint.

Example request

curl --request GET \
       --url https://api.muralpay.com/api/compliance/2b5a8c1d-3f4e-4a2b-9c7d-1e8f6a3b2c4d/reviews/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
       --header 'accept: application/json' \
       --header 'authorization: Bearer $API-KEY'

Example response — approved

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tier": "light",
    "status": {
      "type": "approved",
      "submittedAt": "2026-03-03T12:02:00.000Z",
      "approvedAt": "2026-03-03T14:30:00.000Z"
    },
    "createdAt": "2026-03-03T12:00:00.000Z",
    "requiredAttestations": [
      { "type": "individualPersonalInfoLight" }
    ],
    "uploadedAttestations": [
      {
        "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
        "type": "individualPersonalInfoLight"
      }
    ]
  }

The organization's light tier is now active. Transacting is enabled up to your configured threshold.

Example response — rejected

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tier": "light",
    "status": {
      "type": "rejected",
      "submittedAt": "2026-03-03T12:02:00.000Z",
      "rejectedAt": "2026-03-03T14:30:00.000Z",
      "rejectionDescription": "Provided information does not meet KYC requirements."
    },
    "createdAt": "2026-03-03T12:00:00.000Z",
    "requiredAttestations": [
      { "type": "individualPersonalInfoLight" }
    ],
    "uploadedAttestations": [
      {
        "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
        "type": "individualPersonalInfoLight"
      }
    ]
  }

If the review is rejected, see status.rejectionDescription for the reason. A new compliance review must be created to retry — the rejected review cannot be resubmitted.

Error Cases

404 — Review not found

  {
    "statusCode": 404,
    "message": "Compliance review not found.",
    "error": "Not Found"
  }