Partner Object

The Partner object represents an organization or account within the CarrierX platform that owns, manages, or resells communication services. Each partner operates as an independent entity within the CarrierX ecosystem and can have its own hierarchy of sub-partners, assigned rate plans, billing configuration, and access controls.

This object combines business identity details, technical configuration, and platform relationships that define how the partner interacts with CarrierX resources, APIs, and other partners.

A partner record includes:

• Identification and contact information — such as company name, address, and verified email addresses.
• Financial and billing settings — including payment type, spending limits, prepay thresholds, and balance tracking.
• Access control configuration — including ACL rules defined locally or inherited from parent partners.
• Callback URLs and integrations — for receiving asynchronous events such as SMS or conference activity updates.
• System attributes and operational data — used for platform-level behavior, feature toggles, and system metrics.
• Hierarchy and ownership — with references to the parent partner and, optionally, an associated brand.

Together, these fields define the complete profile and operational boundaries of a partner in the CarrierX ecosystem.

Partner Object Attributes

These fields and values make up the JSON object that gets returned with successful requests.

Attribute	Data Type	Description
acls createupdate	array of objects	The Access Control List, as defined on the Partner object directly. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned on the Partner object itself and cannot be assigned by a parent partner. Refer to the table below for more information.
address1 createupdate	string	The partner address.
address2 createupdate	string	The partner address second field.
attributes createupdate	object	The partner attributes.
available_scopes read only	string	The abilities that this specific partner has. This field is for internal use only. Refer to this table for the complete list of available scopes.
balance read only	number	The current balance of the partner.
billing_email createupdate	string	The partner email address used for billing purposes. If this field is empty, the owner_email is used. In this field, you can add multiple email addresses separated by commas. The system does not validate the format of those addresses.
callbacks createupdate	object	The callback URLs. The allowed callback URL types include: app_conference_call for conference call activity. app_conference_meeting for conference meeting room activity. app_mediator for the activity triggered by Mediator endpoint. sms for text message activity (when an SMS is sent or received). phonenumber_order for getting callbacks with a confirmation of renting a DID from an external provider successfully. phonenumber_messaging_update to get notifications when SMS/MMS messaging is enabled or disabled for a DID.
charge_at createupdate	number	The balance value when the prepay account will be charged.
city createupdate	string	The partner city.
company_name createupdate	string	The partner company name.
compliance_email createupdate	string	The email address (or addresses) of the partner's compliance team — the group responsible for handling complaints related to fraud, abuse, or legal/regulatory violations. If this field is empty, the value from owner_email is used instead. Multiple email addresses can be provided, separated by commas. The system does not validate the format of those addresses.
country_code createupdate	string	The partner country ISO 3166-1 alpha-3 code.
daily_spending_limit createupdate	number	The maximum amount that the partner is allowed to spend on the account per day.
daily_spent_amount read only	number	The amount that the partner has spent on the account during the current day. If this value exceeds the daily_spending_limit, the partner will be suspended until the end of the day.
date_created read only	string	The date and time when the partner was created.
display_id read only	string	The partner unique ID.
login create	string	The login for web and Core API.
name createupdate	string	The partner name.
owner_email createupdate	string	The partner primary email address. Note: only the owner_email is validated by sending a verification email. All other partner email fields (billing_email, compliance_email, tech_email) accept multiple comma-separated addresses and do not trigger verification.
owner_email_pending read only	string	The new primary email address submitted for the partner account but not yet confirmed. When a change is requested, a verification email with a confirmation link is sent to this address. Until the address is verified, it remains in owner_email_pending. Once verified, it replaces the current owner_email.
parent_assigned_acls createupdate	array of objects	The Access Control List, as defined by a parent partner. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned by the parent partner only. Refer to the table below for more information.
parent_sid createupdate	string	The parent partner secure ID.
partner_sid read only	string	The partner secure ID.
password createupdate	string	The partner password for web and Core API. This field is required to create a partner, but is hidden in the serialized copy of the Partner objects received in responses to the requests for the security reasons.
phonenumber createupdate	string	The partner contact phone number.
prepay_amount createupdate	number	The charge amount for prepay customers.
spending_limit create	number	The maximum amount that a partner is allowed to spend on the account.
state createupdate	string	The partner state; two-letter abbreviation code.
status read only	string	The status of the partner. Values accepted in this field are: active for a partner account that is active. canceled for a partner account that was canceled. deleted for a partner account that was removed. suspended* for a partner account that has been suspended due to low balance. soft_suspended* for a partner account that has been partially suspended due to low balance with the following restriction: outbound SMS and dial-outs to the PSTN and to other CarrierX partners are not allowed: the partner is only allowed to receive calls; outbound traffic routing will be limited to its own DIDs and prefixes only, other billable API calls continue to work and accrue charges as usual. unconfirmed for a partner account that has not been confirmed. unverified for a partner account with an email that has not been verified. * Depending on the partner configuration, one of the two partner suspension types is available: suspended or soft_suspended. To learn about the conditions of activating the soft_suspended option, please contact support@carrierx.com.
tech_email createupdate	string	The partner email address used for technical purposes. If this field is empty, the owner_email is used. In this field, you can add multiple email addresses separated by commas. The system does not validate the format of those addresses.
transformations createupdate	array of objects	The list of transformations that a call will undergo. Refer to the transformations section for more information.
zip createupdate	string	The partner zip code.

note

When determining the callback URL, the system will use the first non-empty value from:

1. the callback_url field of the DID object;
2. the callback_url field of the DID Group object;
3. the callbacks.sms field of the Partner object.

Sample Partner Object

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "5",
    "billing_email": null,
    "callbacks": {
      "sms":"https://example.com/sms-callback-url"
    },
    "charge_at": null,
    "city": null,
    "company_name": "ABC",
    "compliance_email": "compliance@example.com",
    "country_code": "USA",
    "daily_spending_limit": "500",
    "daily_spent_amount": "0", 
    "date_created": "2024-01-22T17:16:30.844Z",
    "display_id": "CX57121051",
    "login": "john",
    "name": "John Smith",
    "owner_email": "johnsmith@carrierx.com",
    "owner_email_pending": null,
    "parent_assigned_acls": [],
    "parent_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "partner_sid": "aeda835c-6627-4f4c-ac73-9edcae95640b",
    "payment_type": "postpay",
    "phonenumber": "180045012323",
    "prepay_amount": null,
    "spending_limit": "100",
    "state": "",
    "status": "unverified",
    "tech_email": null,
    "transformations": [],
    "zip": "90804"
}

ACL Object

This object is used with acls and parent_assigned_acls.

Attribute	Data Type	Description
access_control_rules createupdate	array	The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules.
direction createupdate	string	The direction for the access control list. Values accepted in this field are: any to apply the rules from the list to both sent and received calls and messages. inbound to apply the rules from the list to received calls and messages. outbound to apply the rules from the list to sent calls and messages. undirected to apply the rules from the list to actions with no direction specified.
sms_action_false createupdate	string	The action to be executed for SMS messages if no access control rules are applied. Values accepted in this field are accept and reject.
sms_action_true createupdate	string	The action to be executed for SMS messages if any access control rules are applied. Values accepted in this field are accept and reject.
voice_action_false createupdate	string	The action to be executed for calls if no access control rules are applied. Values accepted in this field are: accept to accept the calls. reject403 to reject the call with the 403 status code. reject503 to reject the call with the 503 status code.
voice_action_true createupdate	string	The action to be executed for calls if any access control rules are applied. Values accepted in this field are: accept to accept the calls. reject403 to reject the call with the 403 status code. reject503 to reject the call with the 503 status code.