Update a messaging brand

Correct an existing messaging brand

Update the existing brand when business contact details or an address change. Keep its brand ID; creating another registration is not the way to correct an existing business. Use an enabled API account over HTTPS from a permitted source IP address. The brand must belong to that account.

Start by reading the current record. Keep your local copy private because it contains business identity and contact information.

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID" \
  --output current-brand.json

Preserve the current brand fields

Prepare brand-update.json from the current record, selecting only writable brand fields. Preserve the business identity and other required values while applying the intended correction. Do not send the entire GET response: brandId, identity/status results, timestamps and other response-only fields do not belong in the update.

The update schema requires entityType, displayName, country, email and brandRelationship. Entity-specific rules still apply. For an organization, preserve its legal company name, tax identifier and issuing country, address and industry as applicable. For a sole proprietor, preserve the relevant personal-name and mobile-contact fields instead. Use actual current values, not the placeholders from a registration example.

Brand update field groups
Fields	How to use them
displayName, email, phone	Recognizable brand name and valid contact details. Maximum lengths: 255, 100 and 20 characters. Use international +country-code phone formatting.
street, city, state, postalCode, country	A consistent real business address. Limits: 255, 100, 20, 10 and 2 characters. Use current US state codes where applicable.
entityType, companyName, ein, einIssuingCountry	Legal identity. These changes are restricted when campaigns or external vetting are pending or active. Do not delete working campaigns simply to bypass an identity restriction.
firstName, lastName, mobilePhone, businessContactEmail	Identity or verification contacts when appropriate for the entity type. Limits: 100, 100, 20 and 255 characters.
brandRelationship, vertical	Current relationship and industry codes. Relationship changes are limited to once in three months. The portal’s normal edit form does not offer relationship changes.
website, altBusinessIdType, altBusinessId, stockSymbol, stockExchange	Applicable website, alternate business identity and public-company details. Preserve values needed for the entity’s validation.
referenceId, ipAddress	Supported business-reference and originating-IP metadata. Neither sets account ownership nor acts as the request’s idempotency key.

Use the current messaging catalogues for codes. The update schema does not offer mock as a way to change a brand’s environment. Use the separate reviewed sandbox-to-production workflow rather than changing that flag in an edit.

Submit the reviewed correction

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @brand-update.json \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID"

Use one key for this intended update and retain the exact request-body bytes. Reusing it with a changed method, path, query or body conflicts; reformatting JSON also changes the fingerprint. An in-progress duplicate can return 409 with Retry-After. A completed request can replay its saved result, including an error. Keep request details when reconciling a timeout rather than automatically generating a new key.

Verify the saved record and validation state

A successful update returns HTTP 200 and a direct brand JSON object, without the legacy v3 status/response envelope. Check its brandId, then GET the same brand again and compare the intended fields. The public update route does not take the portal’s changes/version wrapper or provide its optimistic concurrency check. Coordinate concurrent editors; an idempotency key prevents duplicate submission, not another editor’s changes.

The current portal reads the brand, preserves its writable fields, checks the form version before saving, and reads the result again. It locks the core legal identity fields when it finds active campaigns. The registry can impose additional restrictions, including external vetting restrictions, even when a field was offered by a form.

Saving corrected information does not automatically request a new identity verification or guarantee approval. Re-verification is a separate action that can carry a fee; use the portal to review the current state and explicitly confirm any quoted charge. Ordinary brand PUT updates do not trigger a separate registration debit in the current API service. Existing campaign, messaging and other charges remain separate.

Resolve errors without registering a duplicate

Read the HTTP status and JSON error details. For 400, correct the specific field or respect the identity/relationship restriction. For 401, 403 or 404, check credentials, permitted source IP and account ownership. For 429, honor Retry-After. A 500 or 502 can occur after the registry accepted the update; retain any requestId and read the existing record before another submission.

A nonempty but incomplete update response can leave an incomplete local snapshot; an empty success body can retain older snapshot fields. Do not infer field preservation from a bare success status. Read the complete brand back and reconcile any mismatch through support. This guide does not promise atomic registry, local-cache and billing updates.