Add Operator
The ClearIP API references each Operator by its unique ID. To obtain the corresponding human-readable Operator name, a request with the ClearIP Operator ID must be made.
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, a request with the SBC ID must be made.
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/99999999-9999-4999-9999-999999999999
Example Response: View SBC
{
"sbcs": [
{
"createdAt": 1577836800000,
"updatedAt": 1577836800000,
"id": "99999999-9999-4999-9999-999999999999",
"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": "99999999-9999-4999-9999-999999999999",
"operator": "99999999-9999-4999-9999-999999999999"
}
]
}
Update SBC
Once an SBC is created, ClearIP does not allow for the modification of 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 a Service Provider is added, 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, a request with the ClearIP Service Provider ID must be made.
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, the 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, a request with the ClearIP Group ID must be made.
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 for the modification of 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, the 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, a request with the ClearIP User ID must be made.
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 for the modification of 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, the 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"
}
]
}