logo
  • Home
  • API
  • Third-Party Integration
  • Chatbot
  • CallCenter PaaS API
  • Voicebot

Retrieve Company List

This interface is used to retrieve information about multiple customer companies at once.

Request Method

GET /organizations

Request Parameters (Query String)

Parameter NameRequiredTypeDescriptionRestrictions
filter_idNoIntegerCompany filter IDFilter exists
queryNoStringQuery keyword
pageNoIntegerPage number, starts from 1, default is 11 to 100
per_pageNoIntegerNumber per page, default is 1001 to 100

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
metaObjectPagination information, see General Data
organizationsArrayCustomer company list, see Company Data

Example

curl https://demo.udesk.cn/open_api_v1/organizations?page=1&per_page=10&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Return

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "organizations": [
        {
            "id": 1,
            "name": "Test Company 1",
            "domains": "https://www.test1.com",
            "level": "normal",
            "custom_fields": {
                "TextField_1": "Test Text",
                "SelectField_1": ["0"]
            },
            "updated_at": "2017-08-18T12:06:02.000+08:00",
            "description": "This company is only used for example purposes",
            "token": "123456s7hgfd",
            "cellphones": [
                {
                    "id": 173,
                    "content": "13111111111"
                }
            ]
        }
    ]
}

Retrieve Company Details

This interface is used to obtain customer company information that meets specified conditions.

Request Method

GET /organizations/show_org

Request Parameters (Query String)

Parameter NameRequiredTypeDescriptionRestrictions
typeYesStringCondition typeUp to 255 characters
contentYesStringCondition contentUp to 255 characters

type Valid Range

ValueMeaning
idCompany ID
nameCompany Name
tokenCompany External Identifier
For example:

type = id, content = 1 type = name, content = test_name type = token, content = test_token

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
organizationObjectCustomer company information, see Company Data

Example

curl https://demo.udesk.cn/open_api_v1/organizations/show_org?type=name&content=company1&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Return

{
    "code": 1000,
    "organization": {
        "id": 1,
        "name": "Test Company 1",
        "domains": "https://www.test1.com",
        "custom_fields": {
            "TextField_1": "Test Text",
            "SelectField_1": ["0"]
        },
        "updated_at": "2017-08-18T12:06:02.000+08:00",
        "description": "This company is only used for example purposes",
        "token": "123456s7hgfd"
    }
}

Retrieve Company Customer List

This interface is used to obtain customer information of a company that meets specified conditions.

Request Method

GET /organizations/customers

Request Parameters (Query String)

Parameter NameRequiredTypeDescriptionRestrictions
typeYesStringCondition type, see Retrieve Company Details InterfaceUp to 255 characters
contentYesStringCondition content, see Retrieve Company Details InterfaceUp to 255 characters
pageNoIntegerPage number, starts from 1, default is 1
page_sizeNoIntegerNumber per page, default is 20, maximum is 100

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
metaObjectPagination information, see General Data
customersArrayCustomer list, see Customer Data

Example

curl https://demo.udesk.cn/open_api_v1/organizations/customers?type=id&content=1&page=1&page_size=10&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Return

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "customers": [
        {
            "id": 3,
            "nick_name": "Dada 1",
            "level": "normal",
            "description": null,
            "tags": [],
            "first_contact_at": null,
            "last_contact_at": null,
            "first_contact_at_via_phone": null,
            "last_contact_at_via_phone": null,
            "first_contact_at_via_im": null,
            "last_contact_at_via_im": null,
            "owner_id": null,
            "owner_group_id": null,
            "custom_fields": {},
            "open_api_token": null,
            "email": "",
            "other_emails": [],
            "organization_id": 1,
            "cellphones": [
                {
                    "id": 5,
                    "content": "12333334444"
                }
            ],
            "wechat": [],
            "weibo": []
        }
    ]
}

Create Company

This interface is used to create a customer company.

Request Method

POST /organizations

Request Parameters (Request Body)

Attribute NameTypeRequiredDescription
organizationObjectYesCompany information

organization

Attribute NameTypeRequiredDescriptionRestrictions
nameStringYesNameUp to 255 characters
descriptionStringNoDescriptionUp to 255 characters
domainsStringNoDomains
custom_fieldsObjectNoCustom fields

Response Data

The same as the Retrieve Company Details interface.

Example

curl https://demo.udesk.cn/open_api_v1/organizations?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "organization": {
        "name": "Test Company 1",
        "description": "Test Company 1 Description",
        "notes": "",
        "domains": "https://www.test1.com",
        "custom_fields": {
            "TextField_1": "Test Text",
            "SelectField_1": ["0"]
        },
        "token": "123456s7hgfd"
    }
}'

Return

{
    "code": 1000,
    "organization": {
        "id": 1,
        "name": "Test Company 1",
        "domains": "https://www.test1.com",
        "created_at": "2015-01-02T15:04:05.000+08:00",
        "token": "123456s7hgfd",
        "custom_fields": {
            "TextField_1": "Test Text",
            "SelectField_1": ["0"]
        },
        "description": "Test Company 1 Description",
        "customer_count": 0
    }
}

Update Company

This interface is used to modify a customer company that meets specified conditions.

Request Method

PUT /organizations/update_org

Request Parameters (Query String)

The same as the Retrieve Company Details Interface.

Request Parameters (Request Body)

Attribute NameTypeRequiredDescription
organizationObjectYesCompany information, see Company Data

The token of the company cannot be changed if it exists, and can be changed if it does not exist.

Response Data

The same as the Retrieve Company Details interface.

Example

Request

curl https://demo.udesk.cn/open_api_v1/organizations/update_org?type=name&content=Test Company 1&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: application/json' \
-d '
{
    "organization": {
        "description": "Text of Description for Test Company 1"
    }
}'

Return

{
    "code": 1000,
    "organization": {
        "id": 1,
        "name": "Test Company 1",
        "domains": "https://www.test1.com",
        "created_at": "2015-01-02T15:04:05.000+08:00",
        "custom_fields": {
            "TextField_1": "Test Text",
            "SelectField_1": ["0"]
        },
        "description": "Text of Description for Test Company 1",
        "token": "123456s7hgfd",
        "customer_count": 0
    }
}

Delete Company

This interface is used to delete a customer company that meets specified conditions.

Request Method

DELETE /organizations/destroy_org

Request Parameters (Query String)

The same as the Retrieve Company Details Interface.

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
idIntegerID of the deleted company

Example

curl https://demo.udesk.cn/open_api_v1/organizations/destroy_org?type=name&content=Test Company 1&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X DELETE

Return

{
    "code": 1000,
    "id": 1
}

Retrieve Company Custom Fields (Deprecated)

This interface is used to obtain the full list of company custom fields.

Request Method

GET /organizations/custom_fields

Request Parameters

None

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
custom_fieldsArrayList of company custom fields, see Company Data

Example

curl https://demo.udesk.cn/open_api_v1/organizations/custom_fields?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Return

{
    "code": 1000,
    "custom_fields": [
        {
            "id": 10,
            "field_name": "TextField_10",
            "field_title": "Browser",
            "content_type": "text",
            "comment": "",
            "options": null,
            "permission": 3,
            "requirment": false
        },
        {
            "id": 11,
            "field_name": "SelectField_11",
            "field_title": "Joint City",
            "content_type": "chained_droplist",
            "comment": "Content",
            "options": [
                {
                    "0": ["Beijing City", [["Haidian District", [["Zhichun Road"]]]]]
                },
                {
                    "1": ["Tianjin City", [["Heping District"]]]
                }
            ],
            "permission": 2,
            "requirment": false
        }
    ]
}

Data Structure - Company

Attribute NameTypeModifiableDescription
idIntegerNoUnique identifier
nameStringYesName
domainsStringYesDomains
created_atDateTimeNoCreation time
updated_atDateTimeNoLast update time
custom_fieldsObjectYesCustom fields
descriptionStringYesDescription
customer_countIntegerNoNumber of customers
tokenStringNoCustomer company token
levelCompany LevelNoValid values range from normal, vip. If any company of the customer is VIP, the customer is considered as a VIP customer

Error Codes

Error CodeMessageException: MessageDescription
2000Unknown errorInvalid page: xxxpage parameter format is incorrect, for example, negative numbers, letters, spaces, etc.
Unknown errorNonepage_size parameter format is incorrect
Unknown errorSome custom fields must be set when creating a company
Unknown errorName is repeatedWhen creating a company, the company name and an existing company are repeated
Unknown errorOpen api token already existsWhen creating a company, the Open api token and an existing company are repeated
The company has already set a token value, which cannot be modifiedNone
2005Resource not foundCouldn't find Organization with XXXThe provided id format is incorrect or the resource corresponding to the provided id cannot be found
Resource not foundCouldn't find Organization with XXXThe provided name format is incorrect or the resource corresponding to the provided name cannot be found
Resource not foundCouldn't find Organization with XXXThe provided token format is incorrect or the resource corresponding to the provided token cannot be found
2015Non-administrator cannot perform operationsNon-administrator cannot perform operationsThe email used to call the interface must be an administrator email, non-administrators cannot perform operations
2059Open API signature is incorrectOpen API signature is incorrectOpen API signature is incorrect, refer to the Authentication section of the documentation for details
206201Parameter page is not legalNoneRange: 1 to 100
206202Parameter per_page is not legalNoneRange: 1 to 100
marketing@udeskglobal.com
service@udeskglobal.com

Products

Solutions

Resources