Partner Object

This section goes over the parts of the Partner object.

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.
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.
country_code createupdate	string	The partner country ISO 3166-1 alpha-3 code.
daily_spending_limit createupdate	integer	The maximum amount that the partner is allowed to spend on the account per day.
daily_spent_amount read only	integer	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.
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.
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",
    "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": 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.

Create Partner

This request creates a partner.

post

/partners

Sample

A sample POST request to create a partner:

curl -X POST \
'https://api.carrierx.com/core/v2/partners' \
-H 'Content-Type: application/json' \
--data-binary '{"login":"john", "password":"sample_password", "name":"John Smith", "company_name": "ABC", "parent_sid":"", "country_code":"USA", "zip":"90804", "owner_email": "johnsmith@carriex.com", "payment_type": "postpay", "phonenumber": "180045012323", "charge_at": 20, "prepay_amount": "100"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the 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",
    "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": 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"
}

When a partner is created, a verification message is sent to the owner_email, tech_email, and billing_email addresses provided. The email addresses will not appear in the Partner object until the link in the email body has been clicked, thereby confirming the email address and allowing the partner to use CarrierX services.

note

Note that new partners will not appear in a GET request response until the associated email address has been verified.

Required Scopes

To create a Partner object, the partner must have one of the following scopes enabled:

• partners.manage
• partners.create

Body Arguments

JSON representation of the fields and values of the Partner object to be created.

Required fields to create a partner are:

• charge_at
• company_name
• country_code
• login
• owner_email
• password
• payment_type
• phonenumber
• prepay_amount
• zip

note

Note that the login value must be unique.

Refer to this table to view all fields that appear in the Partner object.

Get Partners

This request returns a list of partners matching the criteria in the request URL.

get

/partners

Sample

A sample GET request to get the partners:

curl -X GET \
'https://api.carrierx.com/core/v2/partners' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a list of Partner objects:

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "acls": [],
            "address1": null,
            "address2": null,
            "attributes": {},
            "available_scopes": [
                "accesscontrol.manage",
                "app.manage",
                "calls.manage",
                "countries.manage",
                "endpoints.manage",
                "invoices.manage",
                "lookup.dids.read",
                "oauth.allow_token_scope_update",
                "oauth.manage",
                "oauth.manage_all_tokens",
                "partners.billing_method.manage",
                "partners.read",
                "partners.update",
                "phonenumber.manage",
                "push.manage",
                "rating.manage",
                "shortener.manage",
                "sms.manage",
                "storage.manage",
                "trunk_groups.manage",
                "trunk_groups.trunks.manage",
                "verification.manage"
            ],
            "balance": "4.4",
            "billing_email": "example@example.com",
            "callbacks": {},
            "charge_at": "20",
            "city": null,
            "company_name": "FreeConferenceCall",
            "country_code": "USA",
            "daily_spending_limit": "500",
            "daily_spent_amount": "0",
            "date_created": "2024-05-20T18:32:37.000Z",
            "display_id": "CX15650613",
            "login": "example",
            "name": "John Smith",
            "owner_email": "example@example.com",
            "parent_assigned_acls": [
                {
                    "access_control_rules": [
                        "41f8b2d4-68e4-42f7-43b7-357a090cb1ab"
                    ],
                    "direction": "outbound",
                    "sms_action_false": null,
                    "sms_action_true": null,
                    "voice_action_false": null,
                    "voice_action_true": "reject403"
                },
                {
                    "access_control_rules": [
                        "50d74234-73c7-4da4-819e-6e34c451ed71"
                    ],
                    "direction": "outbound",
                    "sms_action_false": null,
                    "sms_action_true": "reject",
                    "voice_action_false": null,
                    "voice_action_true": null
                }
            ],
            "parent_sid": "be128456-3098-4564-b0d1-67dbceee265f",
            "partner_sid": "6bace9c5-3eef-4f75-8f48-fb98e04408be",
            "payment_type": "prepay",
            "phonenumber": "8448440707",
            "prepay_amount": "100",
            "spending_limit": "500",
            "state": null,
            "status": "active",
            "tech_email": "example@example.com",
            "transformations": [],
            "zip": "90804"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

note

Note that email addresses will not appear in the response until they have been verified.

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Required Scopes

To get information about Partner objects, the partner must have one of the following scopes enabled:

• partners.manage
• partners.read

Get Partner by SID

This request returns data for a partner, targeted by secure ID.

get	/partners/{partner_sid}

Sample

A sample GET request to get the partner by secure ID:

curl -X GET \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the Partner object:

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "351.52",
    "billing_email": "example@example.com",
    "callbacks": {},
    "charge_at": "20",
    "city": null,
    "company_name": "CarrierX",
    "country_code": "USA",
    "daily_spending_limit": "500",
    "daily_spent_amount": "0",
    "date_created": "2023-09-20T21:34:55.000Z",
    "display_id": "CX72521509",
    "login": "example",
    "name": "John Smith",
    "owner_email": "example@example.com",
    "parent_assigned_acls": [
        {
            "access_control_rules": [
                "93525bae-f9a9-446b-b92a-7f421df7a11e"
            ],
            "direction": "outbound",
            "sms_action_false": null,
            "sms_action_true": "accept",
            "voice_action_false": null,
            "voice_action_true": null
        }
    ],
    "parent_sid": "ac38616e-d2e7-4cd6-99ae-b6658f0728b6",
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "payment_type": "prepay",
    "phonenumber": "15162065819",
    "prepay_amount": "100",
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "tech_email": "example@example.com",
    "transformations": [],
    "zip": "90804"
}

note

Note that email addresses will not appear in the response until they have been verified.

This request is enabled for Field Filtering.

Required Scopes

To get information about a Partner object, the partner must have one of the following scopes enabled:

• partners.manage
• partners.read

Path Arguments

Parameter	Data Type	Description
partner_sid required	string	The partner secure ID.

Update Partner

This request updates the Partner object, targeted by secure ID, with the values in the request body.

patch	/partners/{partner_sid}
put	/partners/{partner_sid}

Sample

A sample PATCH request to update the partner targeted by secure ID:

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-H 'Content-Type: application/json' \
--data-binary '{"address1":"4300 E Pacific Coast Hwy"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the updated Partner object:

{
    "acls": [],
    "address1": "4300 E Pacific Coast Hwy",
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "351.52",
    "billing_email": "example@example.com",
    "callbacks": {},
    "charge_at": "20",
    "city": null,
    "company_name": "CarrierX",
    "country_code": "USA",
    "daily_spending_limit": "500",
    "daily_spent_amount": "0",
    "date_created": "2023-09-20T21:34:55.000Z",
    "display_id": "CX72521509",
    "login": "example",
    "name": "John Smith",
    "owner_email": "example@example.com",
    "parent_assigned_acls": [
        {
            "access_control_rules": [
                "93525bae-f9a9-336b-b92a-7f421df7a11e"
            ],
            "direction": "outbound",
            "sms_action_false": null,
            "sms_action_true": "accept",
            "voice_action_false": null,
            "voice_action_true": null
        }
    ],
    "parent_sid": "ac38616e-d2e3-4cd6-99ae-b6658f0728b6",
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0",
    "payment_type": "prepay",
    "phonenumber": "15162065574",
    "prepay_amount": "100",
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "tech_email": "example@example.com",
    "transformations": [],
    "zip": "90804"
}

A Partner object can be updated using either a PATCH or PUT request.

• A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The partner secure ID is passed in the query URL, and the values to be modified are passed in the request body.

  The Partner object also contains nested ACLs, Attributes, Callbacks, Parent Assigned ACLs, and Transformations objects. Refer to this section to learn how nested objects can be updated using the PATCH request.

• A PUT request can be used to update an entire Partner object. The partner secure ID is passed in the query URL, and the entire Partner object is passed in the request body.

note

Note, while all the fields must be present in a PUT request, not all the attribute values may be modified after the initial creation, because when created, some of them become read-only.

Required Scopes

To update a Partner object, the partner must have one of the following scopes enabled:

• partners.manage
• partners.update

Path Arguments

Parameter	Data Type	Description
partner_sid required	string	The partner secure ID.

Query Arguments

Parameter	Data Type	Description
nested_objects	string	Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• acls
• address1
• address2
• attributes
• billing_email
• callbacks
• city
• company_name
• name
• owner_email
• parent_assigned_acls
• phonenumber
• tech_email
• transformations
• zip

Refer to this table to view all fields that appear in the Partner object.

Delete Partner

This request deletes a partner, targeted by secure ID.

delete

/partners/{partner_sid}

Sample

A sample DELETE request to deactivate a partner:

'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

204 status code with an empty body.

note

This action is not possible to accomplish until the selected partner owns sub-partners. All sub-partner accounts must be deleted before a parent partner is deleted.

Required Scopes

To delete a Partner object, the partner must have one of the following scopes enabled:

• partners.manage
• partners.delete

Path Arguments

Parameter	Data Type	Description
partner_sid required	string	The secure ID of the partner to be deleted.