Add Operator
The ClearIP API references each Operator by its unique ID. To obtain the corresponding human-readable Operator name, you must make a request with the ClearIP Operator ID.
Method: POST
URL: https://api.clearip.com/operators
Request Body:
{
operator: {
name: "NAME_HERE",
status: "STATUS_HERE",
comment: "COMMENT_HERE"
}
}
Response Body:
{
"operators": [
{
"createdAt":CREATED_AT_UNIX_TIME_HERE,
"updatedAt":UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_OPERATOR_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE"
}
]
}
View Operator
Method: GET
URL to view specific Operator: https://api.clearip.com/operators/CLEARIP_OPERATOR_ID_HERE
URL to view top 20 Operators by name listed in alphabetical order: https://api.clearip.com/operators?limit=20&skip=0&sort=name%20ASC
Response Body:
{
"operators": [
{
"createdAt":CREATED_AT_UNIX_TIME_HERE,
"updatedAt":UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_OPERATOR_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
Add SBC
The SBC refers to the device that sends SIP Invites to ClearIP. The ClearIP API references each SBC by its unique ID. To obtain the corresponding human-readable SBC name, you must make a request with the SBC ID.
Method: POST
URL: https://api.clearip.com/sbcs
Request Body:
{
"sbc":{
"name": "SBC_NAME_HERE",
"ipAddress": "SBC_PUBLIC_IP_ADDRESS_HERE",
"partition": "PARTITION_VALUE_HERE",
"status": "STATUS_HERE: active, inactive, blocked",
"noFraudDetectedResponseCode": "NO_FRAUD_DETECTED_RESPONSE_CODE_HERE: 503, 404",
"routing":ROUTING_ENABLED_BOOLEAN_HERE,
"includeUserParametersInRoutingResponse":INCLUDE_USER_PARAMETER_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnLrnInSipResponse":LRN_RETURNED_IN_302_BOOLEAN_HERE,
"returnIdsInSipResponse":RETURN_ID_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnRatesInSipResponse":RETURN_RATES_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnReputationScoreInSipResponse":RETURN_REPUTATION_SCORE_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnVerificationStatusInSipResponse":RETURN_VERIFICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnAuthenticationStatusInSipResponse":RETURN_AUTHENTICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"cnamMaximumLength":MAXIMUM_CNAM_LENGTH_RETURNED_HERE,
"cnamHeader": "HEADER_USED_TO_RETURN_CNAM_IN_SIP_RESPONSE_HERE: p-asserted-identity, x-asserted-identity, p-asserted-identity-embedded-in-contact-uri, x-asserted-identity-embedded-in-contact-uri, p-asserted-identity-embedded-in-contact, x-asserted-identity-embedded-in-contact",
"identityHeader": "HEADER_USED_TO_RETURN_IDENTITY_TOKEN_IN_SIP_RESPONSE_HERE: identity, x-identity, identity-embedded-in-contact-uri, x-identity-embedded-in-contact-uri, identity-embedded-in-contact, x-identity-embedded-in-contact",
"localRoutingAlgorithm": "ALGORITHM_TO_DEFINE_LOCAL_CALLS_HERE: intra-rate-center, intra-lata, custom, custom-or-intra-rate-center, custom-or-intra-lata",
"diversionDestination": "DESTINATION_FOR_DIVERTED_CALLS_HERE",
"staticDestination": "STATIC_DESTINATION_HERE",
"minimumCallingNumberLength":MINIMUM_CALLING_NUMBER_LENGTH_HERE,
"minimumCalledNumberLength":MINIMUM_CALLED_NUMBER_LENGTH_HERE,
"comment": "COMMENT_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE"
}
}
Response Body:
{
"sbcs": [
{
"createdAt":CREATED_AT_UNIX_TIME_HERE,
"updatedAt":UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_SBC_ID_HERE",
"name": "SBC_NAME_HERE",
"ipAddress": "SBC_PUBLIC_IP_ADDRESS_HERE",
"partition": "PARTITION_VALUE_HERE",
"status": "STATUS_HERE",
"noFraudDetectedResponseCode": "NO_FRAUD_DETECTED_RESPONSE_CODE_HERE: 503, 404",
"routing":ROUTING_ENABLED_BOOLEAN_HERE,
"includeUserParametersInRoutingResponse":INCLUDE_USER_PARAMETER_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnLrnInSipResponse":LRN_RETURNED_IN_302_BOOLEAN_HERE,
"returnIdsInSipResponse":RETURN_ID_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnRatesInSipResponse":RETURN_RATES_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnReputationScoreInSipResponse":RETURN_REPUTATION_SCORE_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnVerificationStatusInSipResponse":RETURN_VERIFICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnAuthenticationStatusInSipResponse":RETURN_AUTHENTICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"cnamMaximumLength":MAXIMUM_CNAM_LENGTH_RETURNED_HERE,
"cnamHeader": "HEADER_USED_TO_RETURN_CNAM_IN_SIP_RESPONSE_HERE",
"identityHeader": "HEADER_USED_TO_RETURN_IDENTITY_TOKEN_IN_SIP_RESPONSE_HERE",
"localRoutingAlgorithm": "ALGORITHM_TO_DEFINE_LOCAL_CALLS_HERE",
"diversionDestination": "DESTINATION_FOR_DIVERTED_CALLS_HERE",
"staticDestination": "STATIC_DESTINATION_HERE",
"minimumCallingNumberLength":MINIMUM_CALLING_NUMBER_LENGTH_HERE,
"minimumCalledNumberLength":MINIMUM_CALLED_NUMBER_LENGTH_HERE,
"comment": "COMMENT_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE"
}
]
}
View SBC
Method: GET
URL to view specific SBC: https://api.clearip.com/sbcs/CLEARIP_SBC_ID_HERE
URL to view top 20 SBCs by name listed in alphabetical order: https://api.clearip.com/sbcs?limit=20&skip=0&sort=name%20ASC
Response Body:
{
"sbcs": [
{
"createdAt":CREATED_AT_UNIX_TIME_HERE,
"updatedAt":UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_SBC_ID_HERE",
"name": "SBC_NAME_HERE",
"ipAddress": "SBC_PUBLIC_IP_ADDRESS_HERE",
"partition": "PARTITION_VALUE_HERE",
"status": "STATUS_HERE",
"noFraudDetectedResponseCode": "NO_FRAUD_DETECTED_RESPONSE_CODE_HERE",
"routing":ROUTING_ENABLED_BOOLEAN_HERE,
"includeUserParametersInRoutingResponse":INCLUDE_USER_PARAMETER_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnLrnInSipResponse":LRN_RETURNED_IN_302_BOOLEAN_HERE,
"returnIdsInSipResponse":RETURN_ID_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnRatesInSipResponse":RETURN_RATES_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnReputationScoreInSipResponse":RETURN_REPUTATION_SCORE_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnVerificationStatusInSipResponse":RETURN_VERIFICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnAuthenticationStatusInSipResponse":RETURN_AUTHENTICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"cnamMaximumLength":MAXIMUM_CNAM_LENGTH_RETURNED_HERE,
"cnamHeader": "HEADER_USED_TO_RETURN_CNAM_IN_SIP_RESPONSE_HERE",
"identityHeader": "HEADER_USED_TO_RETURN_IDENTITY_TOKEN_IN_SIP_RESPONSE_HERE",
"localRoutingAlgorithm": "ALGORITHM_TO_DEFINE_LOCAL_CALLS_HERE",
"diversionDestination": "DESTINATION_FOR_DIVERTED_CALLS_HERE",
"staticDestination": "STATIC_DESTINATION_HERE",
"minimumCallingNumberLength":MINIMUM_CALLING_NUMBER_LENGTH_HERE,
"minimumCalledNumberLength":MINIMUM_CALLED_NUMBER_LENGTH_HERE,
"comment": "COMMENT_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE"
}
]
}
Example Request: View SBC
Method: GET
URL: https://api.clearip.com/sbcs/046c16a2-647a-4d2f-b486-09fd7d34fefe
Example Response: View SBC
{
"sbcs": [
{
"createdAt": 1623413926240,
"updatedAt": 1623415127270,
"id": "30767ede-9f60-4f9c-9bd3-6a003a1e8653",
"name": "Test",
"ipAddress": "9.9.9.9",
"partition": "",
"status": "active",
"noFraudDetectedResponseCode": "503",
"routing": false,
"includeUserParametersInRoutingResponse": false,
"returnLrnInSipResponse": false,
"returnIdsInSipResponse": false,
"returnRatesInSipResponse": false,
"returnReputationScoreInSipResponse": false,
"returnVerificationStatusInSipResponse": false,
"returnAuthenticationStatusInSipResponse": false,
"cnamMaximumLength": 15,
"cnamHeader": "p-asserted-identity",
"identityHeader": "identity",
"localRoutingAlgorithm": "intra-rate-center",
"diversionDestination": "captcha.clearip.com:5060;transport=tcp",
"staticDestination": "",
"minimumCallingNumberLength": 1,
"minimumCalledNumberLength": 1,
"comment": "",
"reseller": "a00c4269-81bb-4ace-b395-cfe000015289",
"operator": "bf783dcd-78cf-49b7-b75f-ffa4c2c7daf6"
}
]
}
Update SBC
Once an SBC is created, ClearIP does not allow you to modify the values in the following fields: Operator, IP Address, Partition.
All other fields can be updated for existing SBCs.
Method: PATCH
URL: https://api.clearip.com/sbcs/CLEARIP_SBC_ID_HERE
Request Body:
{
"sbc":{
"name": "SBC_NAME_HERE",
"status": "STATUS_HERE",
"noFraudDetectedResponseCode": "NO_FRAUD_DETECTED_RESPONSE_CODE_HERE",
"routing":ROUTING_ENABLED_BOOLEAN_HERE,
"includeUserParametersInRoutingResponse":INCLUDE_USER_PARAMETER_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnLrnInSipResponse":LRN_RETURNED_IN_302_BOOLEAN_HERE,
"returnIdsInSipResponse":RETURN_ID_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnRatesInSipResponse":RETURN_RATES_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnReputationScoreInSipResponse":RETURN_REPUTATION_SCORE_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnVerificationStatusInSipResponse":RETURN_VERIFICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnAuthenticationStatusInSipResponse":RETURN_AUTHENTICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"cnamMaximumLength":MAXIMUM_CNAM_LENGTH_RETURNED_HERE,
"cnamHeader": "HEADER_USED_TO_RETURN_CNAM_IN_SIP_RESPONSE_HERE",
"identityHeader": "HEADER_USED_TO_RETURN_IDENTITY_TOKEN_IN_SIP_RESPONSE_HERE",
"localRoutingAlgorithm": "ALGORITHM_TO_DEFINE_LOCAL_CALLS_HERE",
"diversionDestination": "DESTINATION_FOR_DIVERTED_CALLS_HERE",
"staticDestination": "STATIC_DESTINATION_HERE",
"minimumCallingNumberLength":MINIMUM_CALLING_NUMBER_LENGTH_HERE,
"minimumCalledNumberLength":MINIMUM_CALLED_NUMBER_LENGTH_HERE,
"comment": "COMMENT_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE"
}
}
Response Body:
{
"sbcs": [
{
"createdAt":CREATED_AT_UNIX_TIME_HERE,
"updatedAt":UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_SBC_ID_HERE",
"name": "SBC_NAME_HERE",
"ipAddress": "SBC_PUBLIC_IP_ADDRESS_HERE",
"partition": "PARTITION_VALUE_HERE",
"status": "STATUS_HERE",
"noFraudDetectedResponseCode": "NO_FRAUD_DETECTED_RESPONSE_CODE_HERE: 503, 404",
"routing":ROUTING_ENABLED_BOOLEAN_HERE,
"includeUserParametersInRoutingResponse":INCLUDE_USER_PARAMETER_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnLrnInSipResponse":LRN_RETURNED_IN_302_BOOLEAN_HERE,
"returnIdsInSipResponse":RETURN_ID_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnRatesInSipResponse":RETURN_RATES_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnReputationScoreInSipResponse":RETURN_REPUTATION_SCORE_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnVerificationStatusInSipResponse":RETURN_VERIFICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"returnAuthenticationStatusInSipResponse":RETURN_AUTHENTICATION_STATUS_IN_SIP_RESPONSE_BOOLEAN_HERE,
"cnamMaximumLength":MAXIMUM_CNAM_LENGTH_RETURNED_HERE,
"cnamHeader": "HEADER_USED_TO_RETURN_CNAM_IN_SIP_RESPONSE_HERE",
"identityHeader": "HEADER_USED_TO_RETURN_IDENTITY_TOKEN_IN_SIP_RESPONSE_HERE",
"localRoutingAlgorithm": "ALGORITHM_TO_DEFINE_LOCAL_CALLS_HERE",
"diversionDestination": "DESTINATION_FOR_DIVERTED_CALLS_HERE",
"staticDestination": "STATIC_DESTINATION_HERE",
"minimumCallingNumberLength":MINIMUM_CALLING_NUMBER_LENGTH_HERE,
"minimumCalledNumberLength":MINIMUM_CALLED_NUMBER_LENGTH_HERE,
"comment": "COMMENT_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE"
}
]
}
Add Service Provider
A Service Provider defines a custom set of Groups. After you add a Service provider, ClearIP will return the full record for this Service Provider, including the ID. This is needed to add a Group inside of that Service Provider. The same applies to a User in a Group.
Names must be less than 256 characters long and only contain numbers, letters, spaces, “#”, “@”, “+”, “.”, “,”, “(”, “)”, “-”, or “_”.
Method: POST
URL: https://api.clearip.com/serviceProviders
Request Body:
{
"serviceProvider": {
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE"
}
}
Response Body:
{
"serviceProviders": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
View Service Provider
The ClearIP API references each Service Provider by its unique ID. To obtain the corresponding human-readable Service Provider name, you must make a request with the ClearIP Service Provider ID.
Method: GET
URL: https://api.clearip.com/serviceProviders/CLEARIP_SERVICE_PROVIDER_ID_HERE
Response Body:
{
"serviceProviders": [
{
"createdAt":CREATED_AT_UNIX_TIME_HERE,
"updatedAt":UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
Update Service Provider
Method: PATCH
URL: https://api.clearip.com/serviceProviders/CLEARIP_SERVICE_PROVIDER_ID_HERE
Request Body:
{
"serviceProvider":{
"name": "NAME_HERE",
"status": "STATUS_HERE: active, inactive, blocked",
"comment": "COMMENT_HERE",
}
}
The PATCH request body only needs to contain the fields that need to be updated. Any fields which should remain unchanged can be omitted from the request.
For example, to only change the Status field for a Service Provider, your request can simply contain the Status field and new value. The other fields are unchanged.
{
"serviceProvider":{
"status": "STATUS_HERE: active, inactive, blocked",
}
}
Response Body:
{
"serviceProviders": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
Delete Service Provider
A Service Provider can only be deleted if there are no other records such as SIP Messages or ClearIP policies that reference that Service Provider.
If there are any SIP Messages or ClearIP policies referencing a Service Provider, then the Service Provider cannot be deleted from ClearIP until the records have been deleted or expired.
Method: DELETE
URL: https://api.clearip.com/serviceProviders/CLEARIP_SERVICE_PROVIDER_ID_HERE
Response Body:
{
"serviceProviders": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
Add Group
A Group defines a custom set of Users. A relevant Service Provider and Group must be created before attempting to add a User.
Names must be less than 256 characters long and only contain numbers, letters, spaces, “#”, “@”, “+”, “.”, “,”, “(”, “)”, “-”, or “_”.
If the Status field is set to inactive, ClearIP will return a 403 “Forbidden” immediately. If set to blocked, ClearIP will return a 603 “Decline” immediately. The default value is Active.
Method: POST
URL: https://api.clearip.com/groups
Request Body:
{
"group": {
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE: active, inactive, blocked",
"comment": "COMMENT_HERE"
}
}
Response Body:
{
"groups": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_GROUP_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
View Group
The ClearIP API references each Group by its unique ID. To obtain the corresponding human-readable Group name, you must make a request with the ClearIP Group ID.
Method: GET
URL: https://api.clearip.com/groups/CLEARIP_GROUP_ID_HERE
Response Body:
{
"groups": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_GROUP_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
Update Group
Once a Group is created, ClearIP does not allow you to modify the Service Provider value.
The following fields can be updated for an existing Group: Name, Status, Comment.
Method: PATCH
URL: https://api.clearip.com/groups/CLEARIP_GROUP_ID_HERE
Request Body:
{
"group":{
"name": "NAME_HERE",
"status": "STATUS_HERE: active, inactive, blocked",
"comment": "COMMENT_HERE",
}
}
The PATCH request body only needs to contain the fields that need to be updated. Any fields which should remain unchanged can be omitted from the request.
For example, to only change the Status field for a Group, your request can simply contain the Status field and new value. The other fields are unchanged.
{
"group":{
"status": "STATUS_HERE: active, inactive, blocked",
}
}
Response Body:
{
"groups": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_GROUP_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
Delete Group
A Group can only be deleted if there are no other records such as SIP Messages or ClearIP policies that reference that Group.
If there are any SIP Messages or ClearIP policies referencing a Group, then the Group cannot be deleted from ClearIP until the records have been deleted or expired.
Method: DELETE
URL: https://api.clearip.com/groups/CLEARIP_GROUP_ID_HERE
Response Body:
{
"groups": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_GROUP_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"comment": "COMMENT_HERE",
}
]
}
Add User
A User defines a call source that is identified by only one of the following parameters: user Id, P-Source-Device, originating trunk group, bill to number, or calling number. A single User can only have a single above parameter defined. For example, a User cannot have values defined in both the user Id and P-Source-Device fields. A relevant Service Provider and Group must be created before attempting to add a User.
Names must be less than 256 characters long and only contain numbers, letters, spaces, “#”, “@”, “+”, “.”, “,”, “(”, “)”, “-”, or “_”.
The value entered in the user Id, P-Source-Device, originating trunk group, bill to number, and calling number fields must exactly match the contents (including capitalization) of the header or parameter provided in the SIP Invite.
If the Status field is set to inactive, ClearIP will not use this user and will attempt to find another match. Making a user inactive has the same effect as deleting the user. If no matching user is found, ClearIP will return a 403 “Forbidden” immediately. If set to Blocked, ClearIP will return a 603 “Decline” immediately. The default value is Active.
Method: POST
URL: https://api.clearip.com/users
Request Body:
{
"user": {
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"group": "CLEARIP_GROUP_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE: active, inactive, blocked",
"userId": "SIP_INVITE_USER_ID_HERE",
"pSourceDevice": "SIP_INVITE_P_SOURCE_DEVICE_HERE",
"originatingTrunkGroup": "SIP_INVITE_ORIGINATING_TRUNK_GROUP_HERE",
"billToNumber": "SIP_INVITE_BILL_TO_NUMBER_HERE",
"callingNumber": "SIP_INVITE_CALLING_NUMBER_HERE",
"comment": "COMMENT_HERE"
}
}
Response Body:
{
"users": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_USER_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"group": "CLEARIP_GROUP_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"userId": "USER_ID_HERE",
"pSourceDevice": "P_SOURCE_DEVICE_HERE",
"originatingTrunkGroup": "ORIGINATING_TRUNK_GROUP_HERE",
"billToNumber": "BILL_TO_NUMBER_HERE",
"callingNumber": "CALLING_NUMBER_HERE",
"comment": "COMMENT_HERE"
}
]
}
View User
The ClearIP API references each User by its unique ID. To obtain the corresponding human-readable User name, you must make a request with the ClearIP User ID.
Method: GET
URL: https://api.clearip.com/users/CLEARIP_USER_ID_HERE
Response Body:
{
"users": [
{
"createdAt": CREATED_AT_UNIX_TIME_HERE,
"updatedAt": UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_USER_ID_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"group": "CLEARIP_GROUP_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"userId": "USER_ID_HERE",
"pSourceDevice": "P_SOURCE_DEVICE_HERE",
"originatingTrunkGroup": "ORIGINATING_TRUNK_GROUP_HERE",
"billToNumber": "BILL_TO_NUMBER_HERE",
"callingNumber": "CALLING_NUMBER_HERE",
"comment": "COMMENT_HERE"
}
]
}
Update User
Once a User is created, ClearIP does not allow you to modify the values in the following fields: Service Provider, Group, User ID, P Source Device, Originating Trunk Group, Bill To Number, Calling Number.
The following fields can be updated for existing Users: Name, Status, Comment.
Method: PATCH
URL: https://api.clearip.com/users/CLEARIP_USER_ID_HERE
Request Body:
{
"user":{
"name": "NAME_HERE",
"status": "STATUS_HERE: active, inactive, blocked",
"comment": "COMMENT_HERE",
}
}
The PATCH request body only needs to contain the fields that need to be updated. Any fields which should remain unchanged can be omitted from the request.
For example, to only change the Status field for a User, your request can simply contain the Status field and new value. The other fields are unchanged.
{
"user":{
"status": "STATUS_HERE: active, inactive, blocked",
}
}
Response Body:
{
"users": [
{
"createdAt":CREATED_AT_UNIX_TIME_HERE,
"updatedAt":UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_USER_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"userId": "USER_ID_HERE",
"pSourceDevice": "P_SOURCE_DEVICE_HERE",
"originatingTrunkGroup": "ORIGINATING_TRUNK_GROUP_HERE",
"billToNumber": "BILL_TO_NUMBER_HERE",
"callingNumber": "CALLING_NUMBER_HERE",
"comment": "COMMENT_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"group": "CLEARIP_GROUP_ID_HERE"
}
]
}
Delete User
A User can only be deleted if there are no other records such as SIP Messages or ClearIP policies that reference that User.
If there are any SIP Messages or ClearIP policies referencing a User, then the User cannot be deleted from ClearIP until the records have been deleted or expired.
Method: DELETE
URL: https://api.clearip.com/users/CLEARIP_USER_ID_HERE
Response Body:
{
"users": [
{
"createdAt":CREATED_AT_UNIX_TIME_HERE,
"updatedAt":UPDATED_AT_UNIX_TIME_HERE,
"id": "CLEARIP_USER_ID_HERE",
"name": "NAME_HERE",
"status": "STATUS_HERE",
"userId": "USER_ID_HERE",
"pSourceDevice": "P_SOURCE_DEVICE_HERE",
"originatingTrunkGroup": "ORIGINATING_TRUNK_GROUP_HERE",
"billToNumber": "BILL_TO_NUMBER_HERE",
"callingNumber": "CALLING_NUMBER_HERE",
"comment": "COMMENT_HERE",
"reseller": "CLEARIP_RESELLER_ID_HERE",
"operator": "CLEARIP_OPERATOR_ID_HERE",
"serviceProvider": "CLEARIP_SERVICE_PROVIDER_ID_HERE",
"group": "CLEARIP_GROUP_ID_HERE"
}
]
}