Access Control Rule Object

This section describes the elements of the Access Control Rule object.

Access Control Rule Object Attributes

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

Attribute	Data Type	Description
entries createupdate	array	The list of entries to compare against the field value.
field createupdate	string	The field from the call or SMS to check. This value will be used in comparison with entries.
name createupdate	string	The access control rule name. The value will be set to N/A if not specified otherwise.
operation createupdate	string	Determines how the value is checked. Values accepted in this field are: exact for the exact match of the entries with the field value. prefix for the entries to match only the beginning of the field value. regexp for the entries which are the regular expressions instead of the exact values.
quantifier createupdate	string	The type of comparison to be made between entries and field. Values accepted in this field are: all to determine that all the entries must be matched for the rule to work. any to determine that at least one of the entries must be matched for the rule to work. none to determine that none of the entries must match for the rule to work.
read_only read only	boolean	Shows whether the access control rule can be modified or not. Values accepted in this field are: false to allow the rule modifications. true to protect the rule from being edited. The default value is false for the rules created by the partner, true for the rules created by the parent partner.
rule_sid read only	string	The access control rule secure ID.

Sample Access Control Rule Object

{
    "entries": [
        "1800",
        "1615"
    ],
    "field": "to",
    "name": "N/A",
    "operation": "prefix",
    "quantifier": "any",
    "read_only": false,
    "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}

Create Access Control Rule

This request adds a new Access Control Rule (ACR) for the currently logged in partner.

post	/accesscontrol/rules

Sample

A sample POST request to create an access control rule:

curl -X POST \
'https://api.carrierx.com/core/v2/accesscontrol/rules' \
-H 'Content-Type: application/json' \
--data-binary '{"field":"to", "quantifier":"any", "entries": ["1800","1615"], "operation":"prefix"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the Access Control Rule object:

{
    "entries": [
        "1800",
        "1615"
    ],
    "field": "to",
    "name": "N/A",
    "operation": "prefix",
    "quantifier": "any",
    "read_only": false,
    "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}

Required Scopes

To create an Access Control Rule object, the partner must have one of the following scopes enabled:

• accesscontrol.manage
• accesscontrol.create

Body Arguments

JSON representation of the fields and values of the Access Control Rule object to be created.

Required fields to create an access control rule are:

• entries
• field
• operation
• quantifier

The field parameter should contain the value against which messages or calls will be checked.

• The calling and called field values are specific for voice calls.
• The from (some legacy users may still see the old naming from_did), to (or to_did) and message field values are specific for SMS.

Refer to this table to view all fields that appear in the Access Control Rule object.

Get Access Control Rules

This request returns a list of Access Control Rules (ACRs) that match the given criteria, and that belong to the currently logged-in partner and parent partner.

get	/accesscontrol/rules

Sample

A sample GET request to get access control rules matching the criteria in the request URL:

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/rules?offset=0&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a list of Access Control Rule objects:

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "entries": [
                "18007"
            ],
            "field": "called",
            "name": "1st",
            "operation": "prefix",
            "quantifier": "any",
            "read_only": true,
            "rule_sid": "dafd993d-0e99-4af9-b8fc-436fb01b0bbe"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/accesscontrol/rules?limit=1&offset=1"
    },
    "total": 56
}

A partner will not be able to view ACRs created by sub-partners. The read_only field shows whether or not the ACRs belong to the currently logged-in partner.

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

Required Scopes

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

• accesscontrol.manage
• accesscontrol.read

Get Access Control Rule by SID

This request returns data for a particular access control rule (ACR), targeted by secure ID.

get	/accesscontrol/rules/{rule_sid}

Sample

A sample GET request to get an access control rule, targeted by secure ID:

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/rules/dafd993d-0e99-4af9-b8fc-436fb01b0bbe' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the Access Control Rule object:

{
    "entries": [
        "18007"
    ],
    "field": "called",
    "name": "1st",
    "operation": "prefix",
    "quantifier": "any",
    "read_only": true,
    "rule_sid": "dafd993d-0e99-4af9-b8fc-436fb01b0bbe"
}

The returned ACRs apply to the partner and the parent partner.

This request is enabled for Field Filtering.

Required Scopes

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

• accesscontrol.manage
• accesscontrol.read

Path Arguments

Parameter	Data Type	Description
rule_sid required	string	The Access Control Rule secure ID.

Update Access Control Rule

This request updates an access control rule, targeted by secure ID.

patch	/accesscontrol/rules/{rule_sid}
put	/accesscontrol/rules/{rule_sid}

Sample

A sample PATCH request to update the Access Control Rule object, targeted by secure ID, with the values in the request body:

curl -X PATCH \
'https://api.carrierx.com/core/v2/accesscontrol/rules/c9109b54-13f2-4157-ba23-2984b3a207dc' \
-H 'Content-Type: application/json' \
--data-binary '{"operation":"exact"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the updated Access Control Rule object:

{
    "entries": [
        "1800",
        "1615"
    ],
    "field": "to",
    "name": "N/A",
    "operation": "exact",
    "quantifier": "any",
    "read_only": false,
    "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}

An Access Control Rule 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 message secure ID is passed in the query URL, and the values to be modified are passed in the request body.

• A PUT request can be used to update an entire Access Control Rule object. The message secure ID is passed in the query URL, and the entire Access Control Rule 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 an Access Control Rule object, the partner must have one of the following scopes enabled:

• accesscontrol.manage
• accesscontrol.update

Path Arguments

Parameter	Data Type	Description
rule_sid required	string	The access control rule secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• entries
• field
• name
• operation
• quantifier

note

Note that read_only must be set to false in order to be able to update an Access Control Rule.

Refer to this table to view all fields that appear in the Access Control Rule object.

Delete Access Control Rule

This request deletes an Access Control Rule object, targeted by secure ID.

delete

/accesscontrol/rules/{rule_sid}

Sample

A sample DELETE request to delete an Access Control Rule, targeted by secure ID:

curl -X DELETE \
'https://api.carrierx.com/core/v2/accesscontrol/rules/c9109b54-13f2-4157-ba23-2984b3a207dc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

204 status code with an empty body.

ACRs can only be deleted when associated with the partner. Partners cannot delete an ACR for a parent partner when the value of read_only is true.

Required Scopes

To delete an Access Control Rule object, the partner must have one of the following scopes enabled:

• accesscontrol.manage
• accesscontrol.delete

Path Arguments

Parameter	Data Type	Description
rule_sid required	string	The secure ID of the Access Control Rule to delete.