omnidesk
  • Ticket
    • Message
    • Using forms
    • Contact forms
  • Customers
    • General
    • API sync on contact
    • CSV import
    • API sync before contact
    • Customer lookup
  • Telephone
    • Callflow
    • Numbers
  • E-mail
  • Users
  • Live chat
    • Livechat chatbot and app integration (backend)
  • Facebook
  • Twitter
  • Survey
    • Push data
  • Statistics
    • Statistics API
  • Raw data - BI
  • Security policy
  • Hosting
  • API docs
    • General
    • Authentication
    • REST
  • API specification
    • Documentation for the Omnidesk API endpoints
    • Chat
    • Customer
    • Email
    • Form
    • Formfield
    • Message
    • Notification
    • Raw
    • Ticket
    • User
    • View
    • Statisticsv2
Powered by GitBook
On this page
  1. API specification

Customer

All the endpoints that can be called on the Customer controller.

Endpoints that require the CUSTOMER_READ permission:

  • GET index

  • GET item

  • POST searchByPrimaryExternalId

  • GET timelineByCustomerExternalID

Endpoints that require the CUSTOMER_CUD permission:

  • POST index

  • PUT index

  • PUT item

  • DELETE item

  • POST addChannelOnly

  • PUT updateCustomer

  • DELETE itemChannel

  • DELETE itemPurgeData

  • POST externalEvent

  • POST syncWithCRM

  • POST createCustomerCRUD

PreviousChatNextEmail

index

get

Returns all the customers.

Authorizations
Query parameters
querystring · min: 1OptionalDefault: ""Pattern: ^[0-9a-zA-Z ]+$
itemStartnumberOptionalDefault: 0
itemLimitnumber · max: 99OptionalDefault: 15
Responses
200
index
application/json
get
GET /api/v2/customer HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Accept: */*
200

index

{
  "type": "text",
  "itemStart": 1,
  "itemTotal": 1,
  "itemLimit": 1,
  "items": [
    {
      "id": 1,
      "external_primary_id": "text",
      "brand_name": "text",
      "firstname": "text",
      "lastname": "text",
      "channels": []
    }
  ]
}

item

get

Returns all the data of this customer.

Authorizations
Path parameters
idnumberRequired
Query parameters
brandIDnumberOptional
Responses
200Success
get
GET /api/v2/customer/{id} HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Accept: */*
200Success

No content

item

delete

Permanently deletes this customer.

Authorizations
Path parameters
idnumberRequired
Responses
200Success
delete
DELETE /api/v2/customer/{id} HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Accept: */*
200Success

No content

itemChannel

delete

Permanently deletes a channel endpoint of this customer.

Authorizations
Path parameters
idnumberRequired
Responses
200Success
delete
DELETE /api/v2/customer/channel/{id} HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Accept: */*
200Success

No content

timelineByCustomerExternalID

get

Returns the timeline from this customer by external primary ID.

Authorizations
Query parameters
brand_idnumber · min: 1Required
external_idstring · min: 1Required

External primary ID of the customer.

getTicketHistorybooleanOptional

Include this with any value to also return ticket history for the customer.

Responses
200Success
get
GET /api/v2/customer/timelineByCustomerExternalID?brand_id=1&external_id=text HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Accept: */*
200Success

No content

itemPurgeData

delete

Permanently deletes customer data and related items/tickets.

Authorizations
Path parameters
idnumberRequired
Responses
200Success
delete
DELETE /api/v2/customer/purgeData/{id} HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Accept: */*
200Success

No content

  • GETindex
  • POSTindex
  • PUTindex
  • GETitem
  • PUTitem
  • DELETEitem
  • POSTsearchByPrimaryExternalID
  • POSTsearchByCustomerChannelValue
  • POSTaddChannelOnly
  • PUTupdateCustomer
  • DELETEitemChannel
  • GETtimelineByCustomerExternalID
  • DELETEitemPurgeData
  • POSTexternalEvent
  • POSTsyncWithCRM
  • POSTcreateCustomerCRUD

index

post

Creates a new customer.

If you want to set a custom field, it should always follow the pattern of custom_ followed by the name of the custom field.

Most parameters are optional but depending on the presence of other parameters.

Authorizations
Body
channel_idstring · min: 1Optional

Name or the ID of the channel e.g. email or telephone.

Can only be processed if customer_link_channel is set.

Pattern: ^([0-9]+|email|telephone|facebook|twitter)$
customer_link_channelstringOptional

The name of the address, depending on the channel e.g. a phone number or an email address.

search_customer_channel_valuestring · min: 1Optional

If enable customer search by channels is enabled on the brand, this can be used instead of primary_id

brand_idnumberRequired
primary_idstring · min: 1Optional

The external primary ID of the customer.

Not needed if enable customer search by channels is enabled on this brand. This will take precedent if it is included.

noSyncbooleanOptional

Does not update the ticket with the new linked channel(s) if sent along with the request.

firstnamestring · min: 1OptionalDefault: ""Pattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
lastnamestring · min: 1OptionalDefault: ""Pattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
ticket_idnumberOptional

Allows for instant linking the new customer to a ticket.

extra_emailstring · emailOptional
extra_telephonestring · min: 12OptionalPattern: ^\+[0-9]+$
custom_testfieldstringOptional

This is a custom customer field. See the endpoint description for further explanation.

Responses
200Success
post
POST /api/v2/customer HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 263

{
  "channel_id": "text",
  "customer_link_channel": "text",
  "search_customer_channel_value": "text",
  "brand_id": 1,
  "primary_id": "text",
  "noSync": true,
  "firstname": "",
  "lastname": "",
  "ticket_id": 1,
  "extra_email": "name@gmail.com",
  "extra_telephone": "text",
  "custom_testfield": "text"
}
200Success

No content

index

put

Updates this customer's name.

If you want to update a custom field, it should always follow the pattern of custom_ followed by the name of the custom field.

PrimaryID, brandID and customerID are all optional, but dependent on the presence of at least one.

Authorizations
Body
primaryIDstring · min: 1Optional
brandIDnumberOptional
customerIDnumberOptional
firstnamestring · min: 1OptionalDefault: ""Pattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
lastnamestring · min: 1OptionalDefault: ""Pattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
custom_testfieldstringOptional

This is a custom customer field. See the endpoint description for further explanation.

Responses
200Success
put
PUT /api/v2/customer HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 102

"primaryID='text'&brandID=1&customerID=1&firstname=''&lastname=''&custom_testfield='text'"
200Success

No content

item

put

Updates any fields existing on this customer, including custom fields.

See the example for how to update custom fields. It should always follow the pattern of custom_ followed by the name of the custom field.

If you want to update or add multiple customer channels at once, it should be done in 2 parameters:

  • customerChannelType_0 (corresponding to the channel type ID)

  • customerChannelValue_0 (corresponding to the address of the channel you want to add)

The 0 would be incremental if you choose to do multiple.

Authorizations
Path parameters
idnumberRequired
Body
brandIDnumberRequired
firstnamestring · min: 1OptionalDefault: ""Pattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
lastnamestring · min: 1OptionalDefault: ""Pattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
custom_testfieldstringOptional

This is a custom customer field. Any custom fields you want to update start with custom_ followed by the name of the custom field.

customerChannelType_0stringOptional

This is how you would add/update multiple customer channels at once. the 0 would be incremental if you add/update multiple. This should always be the channel type.

customerChannelValue_0stringOptional

This is how you add the value to the customer channel you want to add. The same goes for how the customerChannelType gets added, only this would be the value.

Responses
200
Successful example
application/json
put
PUT /api/v2/customer/{id} HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 131

"brandID=1&firstname=''&lastname=''&custom_testfield='text'&customerChannelType_0='text'&customerChannelValue_0='text'"
200

Successful example

{
  "message": "Customer updated.",
  "type": "result"
}

searchByPrimaryExternalID

post

Searches for this customer by primary external ID.

Authorizations
Body
primary_idstring · min: 1Required

The external primary ID of the customer.

brand_idnumberRequired
Responses
200Success
post
POST /api/v2/customer/SearchByPrimaryExternalID HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 34

{
  "primary_id": "text",
  "brand_id": 1
}
200Success

No content

searchByCustomerChannelValue

post

Searches for this customer by channel value.

Authorizations
Body
customerChannelValuestring · min: 1Required

The channel value of the customer.

brand_idnumberRequired
Responses
200Success
post
POST /api/v2/customer/SearchByCustomerChannelValue HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 44

{
  "customerChannelValue": "text",
  "brand_id": 1
}
200Success

No content

addChannelOnly

post

Adds a channel to a customer.

Authorizations
Body
customer_idnumberOptional
primary_idstring · min: 1Optional
brand_idnumberRequired
extra_emailstring · email · min: 1Optional
extra_telephonestring · min: 1OptionalPattern: ^\+[0-9]+$
extra_twitterstring · min: 1OptionalPattern: ^[a-zA-Z0-9_ ]+$
extra_facebooknumberOptional
Responses
200Success
post
POST /api/v2/customer/addChannelOnly HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 148

{
  "customer_id": 1,
  "primary_id": "text",
  "brand_id": 1,
  "extra_email": "name@gmail.com",
  "extra_telephone": "text",
  "extra_twitter": "text",
  "extra_facebook": 1
}
200Success

No content

updateCustomer

put

Updates the fields of this customer.

Similar to how PUT item works.

If you want to update a custom field, it should always follow the pattern of custom_ followed by the name of the custom field.

Authorizations
Body
externalPrimaryIDstring · min: 1Required
brandIDnumberRequired
firstnamestring · min: 1RequiredPattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
lastnamestring · min: 1RequiredPattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
custom_testfieldstringOptional

This is a custom customer field. Any custom fields you want to update start with custom_ followed by the name of the custom field.

customerChannelType_0stringOptional

This is how you would add/update multiple customer channels at once. the 0 would be incremental if you add/update multiple. This should always be the channel type.

customerChannelValue_0stringOptional

This is how you add the value to the customer channel you want to add. The same goes for how the customerChannelType gets added, only this would be the value.

Responses
200Success
put
PUT /api/v2/customer/updateCustomer HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 166

"externalPrimaryID='text'&brandID=1&firstname='text'&lastname='text'&custom_testfield='text'&customerChannelType_0='text'&customerChannelValue_0='text'"
200Success

No content

externalEvent

post

Creates a new customer event e.g. an order or marketing mail to the customer timeline.

Authorizations
Body
customer_idnumberOptional
external_idstring · min: 1Optional

The external primary ID of the customer.

brand_idnumberRequired
initiated_bystring · min: 1Required
messagestring · min: 1Required
source_urlstring · min: 1Required
Responses
200Success
post
POST /api/v2/customer/externalEvent HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 110

{
  "customer_id": 1,
  "external_id": "text",
  "brand_id": 1,
  "initiated_by": "text",
  "message": "text",
  "source_url": "text"
}
200Success

No content

syncWithCRM

post

Synchronizes customer data for this customer with the CRM if a CRM lookup URL is configured for the brand.

Authorizations
Body
brandIDnumberRequired
channelstring · enumOptionalPossible values:
addressstring · min: 1Optional
Responses
200Success
post
POST /api/v2/customer/syncWithCRM HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 54

{
  "brandID": 1,
  "channel": "phoneNumber",
  "address": "text"
}
200Success

No content

createCustomerCRUD

post

Creates a customer using the CRUD.

Authorizations
Body
primaryIDstring · min: 1Required

The external primary ID of the customer.

brandIDnumberOptional
firstnamestring · min: 1OptionalPattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\'' ]+$
lastnamestring · min: 1OptionalPattern: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\'' ]+$
custom_testfieldstringOptional

This is a custom customer field. Any custom fields you want to update start with custom_ followed by the name of the custom field.

customerChannelType_0stringOptional

This is how you would add/update multiple customer channels at once. the 0 would be incremental if you add/update multiple. This should always be the channel type.

customerChannelValue_0stringOptional

This is how you add the value to the customer channel you want to add. The same goes for how the customerChannelType gets added, only this would be the value.

Responses
200Success
post
POST /api/v2/customer/createCustomerCRUD HTTP/1.1
Host: {{base_url}}
apiKey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 158

{
  "primaryID": "text",
  "brandID": 1,
  "firstname": "text",
  "lastname": "text",
  "custom_testfield": "text",
  "customerChannelType_0": "text",
  "customerChannelValue_0": "text"
}
200Success

No content