Marmin
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.

Rate limit

30 requests/minute per authenticated account. See Rate limiting for response headers (X-RateLimit-*) and retry guidance.

Request body

See the right panel for a complete request example.

Request fields
FieldTypeRequiredDescriptionValidation
emailstring
Required
EmaraTax-registered email address for the business. Must be the same email used when requesting the OTP.Valid email format.
tinstring
Required
Business Tax Identification Number (TIN) as registered in EmaraTax. Identifies which business you are claiming.Exactly 10 characters; must start with 1.
otpstring
Required
One-time password sent to the EmaraTax email. Must be correct and unexpired. Obtained from the Request claim OTP endpoint.Exactly 6 characters. Expires 2 minutes after it is sent.
Response

Status code: 200 OK

Returns the claimed business profile, including its profile_id. Use this value as business_profile_id in the URL when creating documents (for example POST /api/sales-invoices/{business_profile_id}).

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 documents created with that business_profile_id in the URL path are transmitted under this claimed business.

Response body fields
FieldTypeSourceDescription
idstring (UUID)System ProvidedPrimary identifier for the business profile record. Assigned at claim.
org_idstring (UUID)System ProvidedOrganization that owns this business profile. Set to your organization at claim.
profile_idstringSystem ProvidedHuman-readable business profile identifier. Use as business_profile_id in document API paths.
statusstringSystem ProvidedOnboarding lifecycle status. Typically ONBOARDED immediately after claim.
created_bystring (UUID)System ProvidedUser who created the profile record.
updated_bystring (UUID)System ProvidedUser who last updated the profile record.
created_atnumberSystem ProvidedRecord creation timestamp (Unix time).
updated_atnumberSystem ProvidedRecord last-update timestamp (Unix time).
party_tax_schemeobjectSystem ProvidedUAE VAT/TRN details from EmaraTax onboard. Present when VAT details are present in EmaraTax. See party_tax_scheme below.
namestringUser ProvidedBusiness profile display name. Updatable via Update a business profile.
party_namestringUser ProvidedLegal name of the business entity. Populated from EmaraTax at claim.
party_name_in_local_languagestringUser ProvidedParty name in Arabic or local language.
logo_urlstringUser ProvidedURL to the business profile logo.
emailstringUser ProvidedBusiness contact email. Matches the EmaraTax-registered email used for claim.
telephonestringUser ProvidedBusiness telephone number.
scheme_agency_idstringUser ProvidedRegistration type (TL or CD). See Get Registration Types section for details.
company_idstringUser ProvidedTrade license or registration number. Distinct from VAT/TRN.
authority_namestringUser ProvidedIssuing authority for the trade license. Present when scheme_agency_id is TL.
tinstringUser ProvidedTIN from EmaraTax. Matches the TIN used for claim.
endpoint_idstringUser ProvidedPeppol electronic endpoint identifier.
endpoint_scheme_idstringUser ProvidedScheme for endpoint_id (typically 0235).
postal_addressobjectUser ProvidedUAE postal address. See postal_address below.
Registration vs VAT
FieldMeaning
company_idTrade license or commercial registration number
party_tax_scheme.company_idUAE VAT registration number (TRN) — 15-digit numeric identifier
postal_address
FieldTypeSourceDescription
idstring (UUID)System ProvidedIdentifier of the persisted address record.
street_namestringUser ProvidedStreet name or primary address line.
additional_street_namestringUser ProvidedAdditional street details.
city_namestringUser ProvidedCity or town name.
postal_zonestringUser ProvidedPostal or ZIP code.
country_subentitystringUser ProvidedEmirate or region code (for example DXB). See Get UAE Subdivisions section for details.
address_linestringUser ProvidedAdditional address line.
countrystringUser ProvidedCountry name.
country_codestringUser ProvidedISO 3166-1 alpha-2 country code. Must be AE.
party_tax_scheme
FieldTypeSourceDescription
company_idstringSystem ProvidedUAE VAT registration number (TRN). 15 digits; starts with 1 and ends with 03.
tax_schemestringSystem ProvidedTax scheme identifier. Typically VAT.
Conditional field rules
ConditionAffected fieldsRule
VAT registered in EmaraTaxparty_tax_schemePresent in response when VAT details are present in EmaraTax.
scheme_agency_id is TLauthority_namePresent in response with trade license authority.
Error responses
StatusDescription
400 Bad RequestThe request body is invalid, required fields are missing, or the OTP is invalid or expired (OTP expires after 2 minutes).
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