MarminDeveloper Docs
BusinessesPartnersProduct Wiki

Claim with OTP

Use this endpoint to claim a business profile in Marmin after the business has already selected M A R M I N AI Software Design LLC as its ASP on the EmaraTax portal and requested an OTP using the *Request claim OTP* endpoint. See the right panel for the base URL, request samples, and response JSON.

In the partner onboarding path, authenticate with the account-scoped access token from Obtain Account Access Token (not the partner JWT).

When you call this API, Marmin validates the provided EmaraTax email, TIN, and one-time password (OTP). If they match an eligible business and the OTP is still valid, Marmin links that business to your Marmin organization and returns the full business profile.

Request body
FieldTypeRequiredDescription
emailstring
Required
The EmaraTax-registered email address for the business (for example, user@example.com). Must be the same email used when requesting the OTP.
tinstring
Required
The business Tax Identification Number (TIN) as registered in EmaraTax. Identifies which business you are claiming.
otpstring
Required
The one-time password sent to the EmaraTax email by the *Request claim OTP* endpoint. Must be correct and unexpired.
Response

Status code: 200 OK

Returns the claimed business profile object, including its profile_id. This profile_id is the supplier identifier you will use when generating documents, for example as accounting_supplier_party.profile_id in your e-invoices so the FTA can associate documents with the correct business profile.

Once the claim succeeds:

  • The business is linked to your Marmin organization.

  • You can start issuing documents (such as e-invoices) from this business profile.

  • All subsequent documents that reference this profile_id will be transmitted under this claimed business.

Error responses
StatusDescription
400 Bad RequestThe request body is invalid, required fields are missing, or the OTP is invalid or expired.
401 UnauthorizedAuthentication required or the access token is invalid.
403 ForbiddenThe authenticated user is not allowed to claim this business (for example, claiming for a different organization).
404 Not FoundNo business was found for the provided TIN (or matching EmaraTax email and OTP).
409 ConflictThe business has already been claimed and is linked to a Marmin organization.
500 Internal Server ErrorAn error occurred while processing the request.
Next