Sinch Contact Center Restful Outbound Campaign Interface (OBI) version v1

http://localhost:8080/RI/obi

Description

This interface provides data of outbound campaigns.

Request Header Data Requirements

To GET JSON response, the request must have "Accept = application/json" header.

To GET XML response, the request should have "Accept = application/xml" header.

To POST/PUT JSON data, the request must have "Content-Type = application/json" header.

To POST/PUT XML data, the request should have "Content-Type = application/xml" header.

POST should also have "Accept = text/html" header. It returns the ID of the created object. POST also returns Location header which contains the ID. POST returns code 201 (Created).

PUT and DELETE do not have any response, instead they return code 204 (No Content).

/campaigns

Collection of campaigns.

/campaigns get

get

Get a list of campaigns.

Request
Response

Query Parameters

any fields: (string)
&field1=value1&field2=value2...
Values may contain patterns * and ?
Valid searchable fields: name, dialerId, dialerName, dialingMode, status, dialerStatus, queueId, queueName, customIvrNumber, total, handled, maxCalls, filtered, timeZone
Example:
```
name=TestCampaign*
```
startDate: (string)
Search for campaigns that have the startDate value after the given UTC time
Example:
```
startDate=2020-06-29T12:00:00.000Z
```
startDateEnd: (string)
Search for campaigns that have the startDate value before the given UTC time
Example:
```
startDateEnd=2020-09-29T12:00:00.000Z
```
endDate: (string)
Search for campaigns that have the endDate value after the given UTC time
Example:
```
endDate=2020-06-29T12:00:00.000Z
```
endDateEnd: (string)
Search for campaigns that have the endDate value before the given UTC time
Example:
```
endDateEnd=2020-09-29T12:00:00.000Z
```
registered: (string)
Search for campaigns that have the registered value after the given UTC time
Example:
```
registered=2020-06-29T12:00:00.000Z
```
registeredEnd: (string)
Search for campaigns that have the registered value before the given UTC time
Example:
```
registeredEnd=2020-09-29T12:00:00.000Z
```

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: campaigns

id: required(string - minLength: 32 - maxLength: 32)
Added by the system
name: required(string)
remarks: (string)
dialerId: required(string - minLength: 32 - maxLength: 32)
dialerName: (string)
dialingMode: required(string)
status: (one of Passive, Active, Handled, Expired, Invalid, Deleted)
dialerStatus: (one of OPEN, CLOSING, CLOSING2, CLOSED, PASSIVE, COMPLETED, SUSPEND, EXPIRED, SHUTDOWN)
queueId: required(string - minLength: 32 - maxLength: 32)
queueName: (string)
customIvrNumber: (string)
total: (integer)
handled: (integer)
notHandled: (integer)
maxCalls: (integer)
filtered: (integer)
startDate: (datetime)
endDate: (datetime)
registered: required(datetime)
timeZone: (string)

Example:

[
  {
      "notHandled": 5,
      "dialerName": "Queue Dialer",
      "total": 10,
      "registered": "2020-09-25T07:07:50.243Z",
      "dialerId": "88B8B41C99E6484A94F402EA5E465FC5",
      "dialer": "88B8B41C99E6484A94F402EA5E465FC5",
      "endDate": "2021-02-20T22:00:00Z",
      "startDate": "2020-12-20T22:00:00Z",
      "handled": 5,
      "dialerStatus": "PASSIVE",
      "maxCalls": 0,
      "filtered": 0,
      "dialingMode": "PREDICTIVE",
      "name": "Test Campaign",
      "timeZone": "Europe/Berlin",
      "queueId": "63AA93F493A54C5A8597FCFA670B2382",
      "status": "Passive",
      "queueName": "Test Queue",
      "id": "8A7C98EAF1164F2FAA93B98EECB95D76"
  },
  {
      "notHandled": 5,
      "dialerName": "Queue Dialer",
      "total": 10,
      "registered": "2019-09-25T07:07:50.243Z",
      "dialerId": "88B8B41C99E6484A94F402EA5E465FC5",
      "dialer": "88B8B41C99E6484A94F402EA5E465FC5",
      "handled": 5,
      "dialerStatus": "OPEN",
      "maxCalls": 0,
      "filtered": 0,
      "dialingMode": "PREVIEW",
      "name": "Test Preview Campaign",
      "queueId": "63AA93F493A54C5A8597FCFA670B2382",
      "status": "Active",
      "queueName": "Test Queue",
      "id": "62718C7889CC44F7B944C1A6F6BE9B7F"
  }

]

/campaigns/{campaignId} get

Entity representing a campaign.

get

Get the campaign with campaignId = {campaignId}.

Request
Response

URI Parameters

campaignId: required(string)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

id: required(string - minLength: 32 - maxLength: 32)
Added by the system
name: required(string)
remarks: (string)
dialerId: required(string - minLength: 32 - maxLength: 32)
dialerName: (string)
dialingMode: required(string)
status: (one of Passive, Active, Handled, Expired, Invalid, Deleted)
dialerStatus: (one of OPEN, CLOSING, CLOSING2, CLOSED, PASSIVE, COMPLETED, SUSPEND, EXPIRED, SHUTDOWN)
queueId: required(string - minLength: 32 - maxLength: 32)
queueName: (string)
customIvrNumber: (string)
total: (integer)
handled: (integer)
notHandled: (integer)
maxCalls: (integer)
filtered: (integer)
startDate: (datetime)
endDate: (datetime)
registered: required(datetime)
timeZone: (string)

Example:

{
    "notHandled": 5,
    "dialerName": "Queue Dialer",
    "total": 10,
    "registered": "2020-09-25T07:07:50.243Z",
    "dialerId": "88B8B41C99E6484A94F402EA5E465FC5",
    "dialer": "88B8B41C99E6484A94F402EA5E465FC5",
    "endDate": "2021-02-20T22:00:00Z",
    "startDate": "2020-12-20T22:00:00Z",
    "handled": 5,
    "dialerStatus": "PASSIVE",
    "maxCalls": 0,
    "filtered": 0,
    "dialingMode": "PREDICTIVE",
    "name": "Test Campaign",
    "timeZone": "Europe/Berlin",
    "queueId": "63AA93F493A54C5A8597FCFA670B2382",
    "status": "Passive",
    "queueName": "Test Queue",
    "id": "8A7C98EAF1164F2FAA93B98EECB95D76"
}

/campaigns/{campaignId}/status put

put

Value can be one of Passive, Active.

Request
Response

URI Parameters

campaignId: required(string)

Body

Media type: text/plain

Type: string

Example:

Active

HTTP status code 204

No content - The server has successfully fulfilled the request and there is no additional content to send in the response payload body.

/campaigns/{campaignId}/customers get post

Collection of customers.

get

Get a list of customers.

post

Add a new customer.

Get a list of customers.

Request
Response

URI Parameters

campaignId: required(string)

Query Parameters

includeScript: (string - default: false)
includes script to result
Example:
```
includeScript=true
```
any fields: (string)
&field1=value1&field2=value2...
Values may contain patterns * and ?
Valid searchable fields: externalId, numbers, result, callResult, classifier, callCount, lastBNumber, agentId, dialingMode, previewTime, priority, timeZone
Example:
```
callResult=SUCCESS*
```
date: (string)
Search for customers that have the date value after the given UTC time
Example:
```
date=2020-06-29T12:00:00.000Z
```
dateEnd: (string)
Search for customers that have the date value before the given UTC time
Example:
```
dateEnd=2020-07-29T12:00:00.000Z
```
modificationDate: (string)
Search for customers that have the modificationDate value after the given UTC time
Example:
```
modificationDate=2020-04-29T12:00:00.000Z
```
modificationDateEnd: (string)
Search for customers that have the modificationDate value before the given UTC time
Example:
```
modificationDateEnd=2020-07-29T12:00:00.000Z
```
attributeName: (string)
Search item by attribute name.
Example:
```
attributeName=classification
```
attributeValue: (string)
Search by value of the attribute, attributeName parameter is mandatory in case attributeValue is given.
Example:
```
attributeValue=gold
```
offset: (integer - default: 0)
Skip over a number of elements by specifying an offset value for the query
Example:
```
20
```
limit: (integer - default: 100)
Limit number of elements by specifying a limit value for the query
Example:
```
100
```

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: customers

id: required(string - minLength: 32 - maxLength: 32)
Added by the system
externalId: required(string)
numbers: required(string)
result: (string)
callResult: (string)
classifier: (string)
callCount: (integer)
lastBNumber: (integer)
date: (datetime)
agentId: (string)
dialingMode: (one of PREVIEW, PREDICTIVE)
previewTime: (integer)
priority: (integer)
modificationDate: (datetime)
timeZone: (string)
attributes: (array of object)
Items: items
- name: required(string)
- value: required(string)
script: (object)
- name: required(string)
- answers: required(array of object)
  Items: items
  - question: required(string)
  - answer: required(string)

Example:

[{
       "attributes": {
           "attribute": [
               {
                   "name": "City",
                   "value": "New York"
               },
               {
                   "name": "Classification",
                   "value": "Gold"
               },
               {
                   "name": "Address",
                   "value": "StreetAddress10"
               },
               {
                   "name": "First Name",
                   "value": "Kathy"
               },
               {
                    "name": "Phone1",
                    "value": "0215428754"
               }
           ]
       },
        "script": {
            "answers": [
                {
                    "answer": "Other",
                    "question": "If you would now buy a new tennis racket, which of the following brands would you prefer?
                },
                {
                    "answer": "yes",
                    "question": "Would you be interested to visit our store so we can book an expert to introduce you these rackets in more details?"
                },
                {
                    "answer": "Within 6 months",
                    "question": "OK. When do you think you are going to update your racket so we can give you an call to discuss what we can offer at that time?"
                }
            ],
            "name": "Tennis Sales Script"
        },
       "result": "SUCCESS",
       "date": "9999-12-31T23:59:59Z",
       "dialingMode": "PREDICTIVE",
       "lastBNumber": 0,
       "callCount": 0,
       "modificationDate": "2020-09-29T12:58:28.393Z",
       "externalId": "10",
       "numbers": "0215428754",
       "id": "5C7A1B1A001848B7A86000E10E3B9D5B"
   },
   {
        "attributes": {
            "attribute": [
                {
                    "name": "City",
                    "value": "New York"
                },
                {
                    "name": "ExternalId",
                    "value": "7"
                },
                {
                    "name": "Classification",
                    "value": "Gold"
                },
                {
                    "name": "Postcode",
                    "value": "10001"
                },
                {
                    "name": "Company",
                    "value": "HighCom"
                },
                {
                    "name": "Address",
                    "value": "StreetAddress7"
                },
                {
                    "name": "First Name",
                    "value": "Julie"
                },
                {
                     "name": "Phone1",
                     "value": "951254875"
                },
                {
                     "name": "Phone2",
                     "value": "951254875"
                }
            ]
        },
        "result": "SUCCESS",
        "date": "9999-12-31T23:59:59Z",
        "lastBNumber": 0,
        "callCount": 0,
        "modificationDate": "2020-09-29T12:58:28.393Z",
        "externalId": "7",
        "numbers": "951254875;951254875",
        "id": "3B3BAFB4FD1444478DBF0658EDF389CC"
    }
}]

Add a new customer.

Request
Response

URI Parameters

campaignId: required(string)

Body

Media type: application/json

Type: object

Properties

id: required(string - minLength: 32 - maxLength: 32)
Added by the system
externalId: (string)
If externalId is not given, it is generated by the system.
numbers: (string)
Customer's phone numbers are listed in priority order and separated with semicolon (;). Customer can have up-to 3 numbers. You can define customer phone numbers either by using this field, or by specifying as attributes Phone1, Phone2 and Phone3. Note: in the case numbers are given, then the phone attributes are ignored. It is required to provide phone numbers either by this property or by attributes.
date: (datetime)
agentId: (string)
dialingMode: (one of PREVIEW, PREDICTIVE)
previewTime: (integer)
priority: (integer)
timeZone: (string)
attributes: (array of object)
Attributes of the customer. Note: attributes Phone1, Phone2 and Phone3 are created based on numbers property if that is defined in data. If numbers is not specified, it is mandatory to have at least attribute Phone1.
Items: items
- name: required(string)
- value: required(string)

Example:

{
       "attributes": {
           "attribute": [
               {
                   "name": "City",
                   "value": "New York"
               },
               {
                   "name": "Classification",
                   "value": "Gold"
               },
               {
                   "name": "Address",
                   "value": "StreetAddress10"
               },
               {
                   "name": "First Name",
                   "value": "Kathy"
               }
           ]
       },
       "externalId": "10",
       "numbers": "0215428754;98521542",
       "timeZone": "Europe/Helsinki"
   }
}

HTTP status code 201

Returns the created id.

Body

Media type: text/html

Type: any

Example:

F5168FBDD6914C8DB1C6D0BD64563A39

/campaigns/{campaignId}/customers/{customerId} get delete

Entity representing a customer.

get

Get the customer with customerId = {customerId}.

delete

Delete the customer.

Get the customer with customerId = {customerId}.

Request
Response

URI Parameters

campaignId: required(string)
customerId: required(string)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

id: required(string - minLength: 32 - maxLength: 32)
Added by the system
externalId: required(string)
numbers: required(string)
result: (string)
callResult: (string)
classifier: (string)
callCount: (integer)
lastBNumber: (integer)
date: (datetime)
agentId: (string)
dialingMode: (one of PREVIEW, PREDICTIVE)
previewTime: (integer)
priority: (integer)
modificationDate: (datetime)
timeZone: (string)
attributes: (array of object)
Items: items
- name: required(string)
- value: required(string)
script: (object)
- name: required(string)
- answers: required(array of object)
  Items: items
  - question: required(string)
  - answer: required(string)

Example:

{
       "attributes": {
           "attribute": [
               {
                   "name": "City",
                   "value": "New York"
               },
               {
                   "name": "Classification",
                   "value": "Gold"
               },
               {
                   "name": "Address",
                   "value": "StreetAddress10"
               },
               {
                   "name": "First Name",
                   "value": "Kathy"
               },
               {
                    "name": "Phone1",
                    "value": "0215428754"
               }
           ]
       },
        "script": {
            "answers": [
                {
                    "answer": "Other",
                    "question": "If you would now buy a new tennis racket, which of the following brands would you prefer?
                },
                {
                    "answer": "yes",
                    "question": "Would you be interested to visit our store so we can book an expert to introduce you these rackets in more details?"
                },
                {
                    "answer": "Within 6 months",
                    "question": "OK. When do you think you are going to update your racket so we can give you an call to discuss what we can offer at that time?"
                }
            ],
            "name": "Tennis Sales Script"
        },
       "result": "SUCCESS",
       "date": "9999-12-31T23:59:59Z",
       "dialingMode": "PREDICTIVE",
       "lastBNumber": 0,
       "callCount": 0,
       "modificationDate": "2020-09-29T12:58:28.393Z",
       "externalId": "10",
       "numbers": "0215428754",
       "id": "5C7A1B1A001848B7A86000E10E3B9D5B"
   }

Delete the customer.

Request
Response

URI Parameters

campaignId: required(string)
customerId: required(string)

HTTP status code 204

No content - The server has successfully fulfilled the request and there is no additional content to send in the response payload body.

HTTP status code 404

Not Found

Body

Media type: text/plain

Type: any

Example:

HTTP 404 Not Found

/campaigns/{campaignId}/customers/list post

post

Add array of new customers. Note: recommended maximum amount of new customers in a single request is 100. But it can vary depending on the system.

Request
Response

URI Parameters

campaignId: required(string)

Query Parameters

stopProcessIfInvalidEntriesFound: (boolean - default: false)
If set as true and validation of any of the customers fails, no customer is added to the campaign
Example:
```
stopProcessIfInvalidEntriesFound=true
```

Body

Media type: application/json

Type: array of object

Items: new customer

id: required(string - minLength: 32 - maxLength: 32)
Added by the system
externalId: (string)
If externalId is not given, it is generated by the system.
numbers: (string)
Customer's phone numbers are listed in priority order and separated with semicolon (;). Customer can have up-to 3 numbers. You can define customer phone numbers either by using this field, or by specifying as attributes Phone1, Phone2 and Phone3. Note: in the case numbers are given, then the phone attributes are ignored. It is required to provide phone numbers either by this property or by attributes.
date: (datetime)
agentId: (string)
dialingMode: (one of PREVIEW, PREDICTIVE)
previewTime: (integer)
priority: (integer)
timeZone: (string)
attributes: (array of object)
Attributes of the customer. Note: attributes Phone1, Phone2 and Phone3 are created based on numbers property if that is defined in data. If numbers is not specified, it is mandatory to have at least attribute Phone1.
Items: items
- name: required(string)
- value: required(string)

Example:

[
  {
    "attributes": {
      "attribute": [
        {
          "name": "City",
          "value": "New York"
        },
        {
          "name": "Classification",
          "value": "Gold"
        },
        {
          "name": "First Name",
          "value": "Kathy"
        },
        {
          "name": "Last Name",
          "value": "Smith"
        }
      ]
    },
    "numbers": "+52145200;"
  },
  {
    "attributes": {
      "attribute": [
        {
          "name": "City",
          "value": "New York"
        },
        {
          "name": "Classification",
          "value": "Silver"
        },
        {
          "name": "First Name",
          "value": "Bob"
        },
        {
          "name": "Last Name",
          "value": "Smith"
        }
      ]
    },
    "numbers": "+52145201;"
  },
  {
    "attributes": {
      "attribute": [
        {
          "name": "City",
          "value": "London"
        },
        {
          "name": "Classification",
          "value": "Gold"
        },
        {
          "name": "First Name",
          "value": "John"
        },
        {
          "name": "Last Name",
          "value": "Smith"
        }
      ]
    },
    "numbers": "+52145202;"
  },
  {
    "attributes": {
      "attribute": [
        {
          "name": "City",
          "value": "Helsinki"
        },
        {
          "name": "Classification",
          "value": "Gold"
        },
        {
          "name": "First Name",
          "value": "Keith"
        },
        {
          "name": "Last Name",
          "value": "Smith"
        }
      ]
    },
    "numbers": "+52145203;"
  },
  {
    "attributes": {
      "attribute": [
        {
          "name": "City",
          "value": "New York"
        },
        {
          "name": "Classification",
          "value": "Gold"
        },
        {
          "name": "First Name",
          "value": "Kate"
        },
        {
          "name": "Last Name",
          "value": "Smith"
        }
      ]
    },
    "numbers": "+52145204;"
  }
]

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: items

statusCode: required(number)
Status code of one customer item. Value is 201 in case the customer was validated and created and 200 if only the validation succeeded but process was stopped. Any other value is error code.
id: (string)
error: (string)

Examples:

All customers added:

[{
    "statusCode": 201,
    "id": "0CED774B58EB4CDCBEE697232C22761B"
}, {
    "statusCode": 201,
    "id": "26B8737120BF4C5B86DC13719B335AAB"
}, {
    "statusCode": 201,
    "id": "BF64E255797B4B36B66A778E09C47A19"
}, {
    "statusCode": 201,
    "id": "EF47982E0F244E189669E25BBFF0445F"
}, {
    "statusCode": 201,
    "id": "5AB0D9BDD4E84587B85AFE598A70E50F"
}, {
    "statusCode": 201,
    "id": "EFFD057BE7D44ACF8A2DBFA45A79B46A"
}, {
    "statusCode": 201,
    "id": "BB979E48ABBB48E1B3DBEFCE2CC80411"
}, {
    "statusCode": 201,
    "id": "6A9021F8685A44738DE89671B456B528"
}, {
    "statusCode": 201,
    "id": "5A6D77C61F3943A1A53E39D76130D597"
}, {
    "statusCode": 201,
    "id": "BBE6C534E2274808BC7A643B339C6194"
}]

Validation failure - stopProcessIfInvalidEntriesFound=false:

[{
    "statusCode": 201,
    "id": "0BBBE00A20444BA1A6E9615AF40FA7E1"
}, {
    "statusCode": 201,
    "id": "D11CF178F2A3425EBAEF829FD7E3B008"
}, {
    "statusCode": 201,
    "id": "35A5A62373434047B6CCC04DB5AF0762"
}, {
    "error": "Invalid numbers: '+number;'",
    "statusCode": 400
}, {
    "statusCode": 201,
    "id": "4D6F39E59ADE49C88F56C08633950F2A"
}, {
    "statusCode": 201,
    "id": "AFE892D30FF7495D846AC3A09ABC9836"
}, {
    "statusCode": 201,
    "id": "86B7EDE8A2BF4B60A2CD0245D7EE9557"
}, {
    "statusCode": 201,
    "id": "06BF1776F411471CA3FB6ABD97447D09"
}]

Validation failure - stopProcessIfInvalidEntriesFound=true:

[{
    "statusCode": 200
}, {
    "statusCode": 200
}, {
    "statusCode": 200
}, {
    "statusCode": 200
}, {
    "statusCode": 200
}, {
    "error": "Invalid externalId: 007 : Value is not unique",
    "statusCode": 400
}, {
    "statusCode": 200
}, {
    "error": "Invalid externalId: 007 : Value is not unique",
    "statusCode": 400
}, {
    "statusCode": 200
}, {
    "statusCode": 200
}]

Sinch Contact Center Restful Outbound Campaign Interface (OBI) version v1

/campaigns

get /campaigns

Query Parameters

HTTP status code 200

Body

get /campaigns/{campaignId}

URI Parameters

HTTP status code 200

Body

put /campaigns/{campaignId}/status

URI Parameters

Body

HTTP status code 204

get /campaigns/{campaignId}/customers

URI Parameters

Query Parameters

HTTP status code 200

Body

post /campaigns/{campaignId}/customers

URI Parameters

Body

HTTP status code 201

Body

get /campaigns/{campaignId}/customers/{customerId}

URI Parameters

HTTP status code 200

Body

delete /campaigns/{campaignId}/customers/{customerId}

URI Parameters

HTTP status code 204

HTTP status code 404

Body

post /campaigns/{campaignId}/customers/list

URI Parameters

Query Parameters

Body

HTTP status code 200

Body