Marmin
BusinessesPartnersProduct Wiki

Update a business profile

Updates an existing business profile. See the right panel for the base URL, request sample, and response JSON.

Note: Complete the profile with all operational details so webhooks and invoice transmission work correctly. After claim, profiles often start in ONBOARDED or LINKED status until required fields are filled.

Rate limit

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

Path parameters
ParameterTypeRequiredDescription
profileIdstring
Required
The profile_id of the business profile to update (for example MBP-00001).
Request body

Every update request must include scheme_agency_id and postal_address with country_code = AE. Other fields are optional for partial updates. Fields populated by EmaraTax cannot be changed. See the right panel for a complete request example.

FieldTypeRequiredDescriptionValidation
scheme_agency_idstring
Required
Registration type. Required on every update request.Only TL or CD. See Get Registration Types section for details.
postal_addressobject
Required
UAE postal address. Required on every update request.country_code must be AE. See Request postal_address below.
company_idstring
Conditional
Commercial register or trade license number.Required when scheme_agency_id is provided.
authority_namestring
Optional
Authority that issued the trade license.Optional. Required only when scheme_agency_id is TL and registration details are included.
tinstring
Conditional
TIN from EmaraTax. Required for document exchange.Exactly 10 characters; must start with 1.
endpoint_idstring
Conditional
Peppol electronic endpoint identifier.Required for document exchange.
namestring
Optional
Business profile display name.Non-empty when sent.
party_namestring
Optional
Legal name of the business entity.Non-empty when sent.
party_name_in_local_languagestring
Optional
Party name in Arabic or local language.
logo_urlstring
Optional
URL to the business profile logo image.Valid URL when sent.
endpoint_scheme_idstring
Optional
Scheme for endpoint_id. Typically 0235.See Get Electronic Address Schemes section for details.
emailstring
Optional
Business contact email.Valid email format.
telephonestring
Optional
Business telephone number.
Request postal_address
FieldTypeRequiredDescriptionValidation
street_namestring
Required
Street name or primary address line.Non-empty.
city_namestring
Required
City or town name.Non-empty.
country_subentitystring
Required
Emirate or region code (for example DXB).Valid UAE subdivision. See Get UAE Subdivisions section for details.
countrystring
Required
Country name.Non-empty.
country_codestring
Required
ISO 3166-1 alpha-2 country code.Must be AE.
additional_street_namestring
Optional
Additional street details.
postal_zonestring
Optional
Postal or ZIP code.
address_linestring
Optional
Additional address line.
Tax immutability

Do not send tax_identifier, tax_scheme, or party_tax_scheme. VAT/TRN is set during EmaraTax onboard only. Sending tax fields returns 400 Bad Request:

  • "Tax details cannot be changed" — when VAT details are already present in EmaraTax for the profile

  • "Tax details cannot be added via profile edit" — when VAT details are not present in EmaraTax for the profile

Conditional field rules
ConditionAffected fieldsRule
scheme_agency_id is providedcompany_idcompany_id is required.
scheme_agency_id is TLauthority_nameauthority_name is required.
postal_address is sentstreet_name, city_name, country_subentity, country, country_codeAll are required within postal_address. postal_zone is optional.
Any business profilepostal_address.country_codeMust be AE.
Any business profilescheme_agency_idOnly TL or CD.
Document exchangescheme_agency_id, company_id, tin, endpoint_id, postal_addressAll required for webhook delivery and invoice transmission.
Response

Status code: 200 OK

Returns the updated business profile with all fields reflecting the changes made.

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.
profile_idstringSystem ProvidedHuman-readable business profile identifier (for example MBP-00001). Use as business_profile_id in document API paths.
statusstringSystem ProvidedOnboarding lifecycle status (for example ONBOARDED, LINKED, COMPLETED).
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; omitted otherwise. Cannot be changed via update. See party_tax_scheme below.
namestringUser ProvidedBusiness profile display name.
party_namestringUser ProvidedLegal name of the business entity.
party_name_in_local_languagestringUser ProvidedParty name in Arabic or local language.
logo_urlstringUser ProvidedURL to the business profile logo.
emailstringUser ProvidedBusiness contact email.
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 in party_tax_scheme.company_id.
authority_namestringUser ProvidedIssuing authority for the trade license. Present when scheme_agency_id is TL.
tinstringUser ProvidedTIN from EmaraTax.
endpoint_idstringUser ProvidedPeppol electronic endpoint identifier.
endpoint_scheme_idstringUser ProvidedScheme for endpoint_id (typically 0235). See Get Electronic Address Schemes section for details.
postal_addressobjectUser ProvidedUAE postal address. See Response 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
Response 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. See Get Countries section for details.
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. See Get Tax Schemes section for details.
Error responses
StatusDescription
400 Bad RequestInvalid request parameters or validation failed. The response includes field-specific errors.
401 UnauthorizedAuthentication required or invalid token.
403 ForbiddenUser not authorized to update this business profile.
404 Not FoundBusiness profile not found.
500 Internal Server ErrorAn error occurred while processing the request.
Next