Contact

Last updated:2023-04-10

You can query, add, delete, and update the SMS contact list through the following interface.

Query contact list

Return basic information of SMS contact list

URL

https://sms.api.engagelab.cc/v1/contact_lists
          https://sms.api.engagelab.cc/v1/contact_lists

        
This code block in the floating window

HTTP Request Method

GET
          GET

        
This code block in the floating window

Request-Headers

Header Type Required Description
Authorization String true Basic base64(sms_user:sms_key)

Parameter Description

Parameter Type Required Description
offset Integer no offset position, [0-], defaults to 0
limit Integer no amount, [0-100],defaults to 100
contact_list_name string no name of contact list,supports fuzzy queries

Request Example

curl -X GET "https://sms.api.engagelab.cc/v1/contact_lists?contact_list_name=test" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
          curl -X GET "https://sms.api.engagelab.cc/v1/contact_lists?contact_list_name=test" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"

        
This code block in the floating window

Returned Value Description

Parameter Description
contact_list_id ID of contact list
contact_list_name name of contact list
description contact list description
member_count count of contact in the list
create_time time of contact list creation
update_time time of contact list modification

Returned Value Example

{ "result": [{ "contact_List_id": 998, "contact_list_name": "test", "description": "", "member_count": 4, "create_time": "2016-05-10T15:18:38+0800", "update_time": "2016-05-11T10:04:20+0800" }, { "contact_List_id": 999, "contact_list_name": "test2", "description": "", "member_count": 1, "create_time": "2016-06-29T12:54:59+0800", "update_time": "2016-06-29T12:54:59+0800" } ], "count":2 "total": 10 }
          {
        "result": [{
                "contact_List_id": 998,
                "contact_list_name": "test",
                "description": "",
                "member_count": 4,
                "create_time": "2016-05-10T15:18:38+0800",
                "update_time": "2016-05-11T10:04:20+0800"
            },
            {
                "contact_List_id": 999,
                "contact_list_name": "test2",
                "description": "",
                "member_count": 1,
                "create_time": "2016-06-29T12:54:59+0800",
                "update_time": "2016-06-29T12:54:59+0800"
            }
        ],
        "count":2
        "total": 10
    
}

        
This code block in the floating window

Add contact list

Return contact list information for successfully added contacts

URL

https://sms.api.engagelab.cc/v1/contact_lists
          https://sms.api.engagelab.cc/v1/contact_lists

        
This code block in the floating window

HTTP Request Method

POST
          POST

        
This code block in the floating window

Content-type

application/json
          application/json

        
This code block in the floating window

Request-Headers

Header Type Required Description
Authorization String true Basic base64(sms_user:sms_key)

Parameter Description

Parameter Type Required Description
contact_list_name string yes contact list name, only supports numbers, letters, underscores, or dashes, with a maximum length of 48 characters
description string no descriptive information, up to 255 characters long

Request Example

curl -X POST "https://sms.api.engagelab.cc/v1/contact_lists" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>" --header "Content-Type: application/json" --data '{ "contact_list_name": "beijing", "description": "test" }'
          curl -X POST "https://sms.api.engagelab.cc/v1/contact_lists" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>" 
--header "Content-Type: application/json" 
--data '{
    "contact_list_name": "beijing",
    "description": "test"
}'  

        
This code block in the floating window

Returned Value Description

Parameter Description
contact_list_id ID of contact list
contact_list_name name of contact list
description contact list description
member_count count of contact in the list
create_time time of contact list creation
update_time time of contact list modification

Returned Value Example

Response-success

HTTP Status: 200

{ "result": { "contact_list_id": 35, "contact_list_name": "beijing", "description": "test", "member_count": 28, "create_time": "2016-08-02T14:06:10+0800", "update_time": "2017-05-19T10:55:24+0800" } }
          {
    "result": {
            "contact_list_id": 35,
            "contact_list_name": "beijing",
            "description": "test",
            "member_count": 28,
            "create_time": "2016-08-02T14:06:10+0800",
            "update_time": "2017-05-19T10:55:24+0800"	
    }
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Unauthorized." }
          {
    
    "code": 30000,
    "message": "Unauthorized."
}

        
This code block in the floating window

Response-error

HTTP Status :400

// example of failed return results { "code": 35004, "message": "contact_list_name cannot be empty" }
          // example of failed return results
{
    "code": 35004,
        "message": "contact_list_name cannot be empty"
}

        
This code block in the floating window

Modify contact list

Return the basic information of the successfully updated contact list

URL

https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}
          https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}

        
This code block in the floating window

HTTP Request Method

PUT
          PUT

        
This code block in the floating window

Content-type

application/json
          application/json

        
This code block in the floating window

Request-Headers

Header Type Required Description
Authorization String true Basic base64(sms_user:sms_key)

Parameter Description

Parameter Type Required Description
contact_list_name string no contact list name, only supports numbers, letters, underscores, or dashes, with a maximum length of 48 characters
description string no descriptive information, up to 255 characters long

Tips: 1.The list time is only updated when 'contact_listname' and 'description' are updated, and the list update time is not updated when updating members.

Request Example

curl -X PUT "https://sms.api.engagelab.cc/v1/contact_lists/1234" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>" --header "Content-Type: application/json" --data '{ "contact_list_name": "shanghai", "description": "222" }'
          curl -X PUT "https://sms.api.engagelab.cc/v1/contact_lists/1234"
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>" 
--header "Content-Type: application/json" 
--data '{
    "contact_list_name": "shanghai",
    "description": "222"
}'  

        
This code block in the floating window

Returned Value Description

Parameter Description
count number of successful modifications

Returned Value Example

Response-success

HTTP Status: 200

{ "count":1 }
          {
    "count":1
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Unauthorized." }
          {
    
    "code": 30000,
    "message": "Unauthorized."
}

        
This code block in the floating window

Response-error

HTTP Status :400

// example of failed return results { "code": 35004, "message": "contact_list_name cannot be empty" }
          // example of failed return results
{
    "code": 35004,
        "message": "contact_list_name cannot be empty"
}

        
This code block in the floating window

Delete contact list

Return basic information on whether the submission was successful

URL

https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}
          https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}

        
This code block in the floating window

HTTP Request Method

DELETE
          DELETE

        
This code block in the floating window

Content-type

application/x-www-form-urlencoded
          application/x-www-form-urlencoded

        
This code block in the floating window

Request-Headers

Header Type Required Description
Authorization String true Basic base64(sms_user:sms_key)

Request Example

curl -X DELETE "https://sms.api.engagelab.cc/v1/contact_lists/1234" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
          curl -X DELETE "https://sms.api.engagelab.cc/v1/contact_lists/1234" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"

        
This code block in the floating window

Returned Value Description

Parameter Description
count count of deleted lists

Returned Value Example

Response-success

HTTP Status: 200

{ "count": 1 }
          {
"count": 1 
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Unauthorized." }
          {
    
    "code": 30000,
    "message": "Unauthorized."
}

        
This code block in the floating window

Response-error

HTTP Status :400

// example of failed return results { "code": 35008, "message": "The contactListName does not exist" }
          // example of failed return results
{
    "code": 35008,
        "message": "The contactListName does not exist"
}

        
This code block in the floating window

You can query, add, delete, and update members of the SMS contact list through the following interface.

Query list member

Return basic information of members in the SMS contact list

URL

https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}/members
          https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}/members

        
This code block in the floating window

HTTP Request Method

GET
          GET

        
This code block in the floating window

Request-Headers

Header Type Required Description
Authorization String true Basic base64(sms_user:sms_key)

Parameter Description

Parameter Type Required Description
offset Integer no offset position, [0-], defaults to 0
limit Integer no amount, [0-100],defaults to 100
phone string no member phone number, supports fuzzy queries
member_ids string no member ID, multiple for use; Number separated, up to 100

Request Example

curl -X GET "https://sms.api.engagelab.cc/v1/contact_lists/1025/members?phone=15652496875" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
          curl -X GET "https://sms.api.engagelab.cc/v1/contact_lists/1025/members?phone=15652496875" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"

        
This code block in the floating window

Returned Value Description

Parameter Description
member_id ID of member
phone phone of member
name member name
vars variables
create_time time of contact list creation
update_time time of contact list modification

Returned Value Example

{ "result": [ { "member_id": 440164, "phone": "18********", "name": "", "vars": "{'beizhu':'hello'}", "create_time": "2016-10-18T15:13:27+0800", "update_time": "2016-10-18T15:13:27+0800", }, { "member_id": 440964, "phone": "13********", "name": "", "vars": "{'beizhu':'ss'}", "create_time": "2016-10-18T15:13:27+0800", "update_time": "2016-10-18T15:13:27+0800", } ], "total": 2, "count": 2 }
          {
    "result": [
          {
                "member_id": 440164,
                "phone": "18********",
                "name": "",
                "vars": "{'beizhu':'hello'}",
                "create_time": "2016-10-18T15:13:27+0800",
                "update_time": "2016-10-18T15:13:27+0800",
            },
            {
                "member_id": 440964,
                "phone": "13********",
                "name": "",
                "vars": "{'beizhu':'ss'}",
                "create_time": "2016-10-18T15:13:27+0800",
                "update_time": "2016-10-18T15:13:27+0800",
            }
        ],
        "total": 2,
        "count": 2
}

        
This code block in the floating window

Add list member

Add contact list members

URL

https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}/members
          https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}/members

        
This code block in the floating window

HTTP Request Method

POST
          POST   

        
This code block in the floating window

Content-type

application/json
          application/json

        
This code block in the floating window

Request-Headers

Header Type Required Description
Authorization String true Basic base64(sms_user:sms_key)

Parameter Description

Parameter Type Required Description
members Array [object] yes lists of members,Up to 1000 members.
phone string yes phone,International phone number format
name string no name of member,Maximum 48 characters
vars object no variables,Maximum is 1 KB

Tips:

  1. When adding vars variables, note that the key does not need to be marked with '%', and the length of the key cannot exceed 32 characters.
  2. In the vars variable, the variable whose key is name will be overwritten by the Parameter name.

Request Example

curl -X POST "https://sms.api.engagelab.cc/v1/contact_lists/1024/members" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>" --header "Content-Type: application/json" --data '{ "members": [ { "phone": "+86158452369825", "name": "aaa", "vars": {"sex":"male","code":"1"} }, { "phone": "+8618754265414", "name": "aaa", "vars": {"sex":"female","code":"2"} } ] }'
          curl -X POST "https://sms.api.engagelab.cc/v1/contact_lists/1024/members"
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>" 
--header "Content-Type: application/json" 
--data '{
    "members": [
        {
            "phone": "+86158452369825",
            "name": "aaa",
            "vars": {"sex":"male","code":"1"}
        },
        {
            "phone": "+8618754265414",
            "name": "aaa",
            "vars": {"sex":"female","code":"2"}
        }
    ]
}'  

        
This code block in the floating window

Returned Value Description

Parameter Description
count count of added members
invalid Invalid member

Returned Value Example

Response-success

HTTP Status: 200

{ "result": { "count": 1, "invalid": ["130****"] } }
          {
   "result": {
        "count": 1,
        "invalid": ["130****"]
    }
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Unauthorized." }
          {
    
    "code": 30000,
    "message": "Unauthorized."
}

        
This code block in the floating window

Response-error

HTTP Status :400

// example of failed return results { "code": 35008, "message": "The contactListId does not exist" }
          // example of failed return results
{
    "code": 35008,
        "message": "The contactListId does not exist"
}

        
This code block in the floating window

Modify list member

Update contact list members

URL

https://sms.api.engagelab.cc/v1/contact_lists/{contact_member_id}}/members/{member_id}
          https://sms.api.engagelab.cc/v1/contact_lists/{contact_member_id}}/members/{member_id}

        
This code block in the floating window

HTTP Request Method

PUT
          PUT 

        
This code block in the floating window

Content-type

application/json
          application/json

        
This code block in the floating window

Request-Headers

Header Type Required Description
Authorization String true Basic base64(sms_user:sms_key)

Parameter Description

Parameter Type Required Description
member Object yes member of contact list
phone string no phone,International phone number format
name string no name of member,Maximum 48 characters
vars object no variables,Maximum is 1 KB. The length of the key cannot exceed 32 characters

Request Example

curl -X POST "https://sms.api.engagelab.cc/v1/contact_lists/1024/members/251224" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>" --header "Content-Type: application/json" --data '{ "member": { "phone": "158452369825", "name": "aaa", "vars": {"sex":"male","code":"1"} } }'
          curl -X POST "https://sms.api.engagelab.cc/v1/contact_lists/1024/members/251224"
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>" 
--header "Content-Type: application/json" 
--data '{
    "member": 
        {
            "phone": "158452369825",
            "name": "aaa",
            "vars": {"sex":"male","code":"1"}
        }
    
}'  

        
This code block in the floating window

Returned Value Description

Parameter Description
count count of modified contact

Returned Value Example

Response-success

HTTP Status: 200

{ "count": 1 }
          {
        "count": 1
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Unauthorized." }
          {
    
    "code": 30000,
    "message": "Unauthorized."
}

        
This code block in the floating window

Response-error

HTTP Status :400

// example of failed return results { "code": 35008, "message": "The contactListId does not exist" }
          // example of failed return results
{
    "code": 35008,
        "message": "The contactListId does not exist"
}

        
This code block in the floating window

Delete list member

Return whether the deletion was successful

URL

https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}/members/{member_id}
          https://sms.api.engagelab.cc/v1/contact_lists/{contact_list_id}/members/{member_id}

        
This code block in the floating window

HTTP Request Method

DElETE
          DElETE

        
This code block in the floating window

Content-type

application/x-www-form-urlencoded
          application/x-www-form-urlencoded

        
This code block in the floating window

Request-Headers

Header Type Required Description
Authorization String true Basic base64(sms_user:sms_key)

Request Example

curl -X DELETE "https://sms.api.engagelab.cc/v1/contact_lists/11/members/1234" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
          curl -X DELETE "https://sms.api.engagelab.cc/v1/contact_lists/11/members/1234" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"

        
This code block in the floating window

Returned Value Description

Parameter Description
count count of deleted contact

Returned Value Example

Response-success

HTTP Status: 200

{ "count": 1 }
          {
"count": 1 
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Unauthorized." }
          {
    
    "code": 30000,
    "message": "Unauthorized."
}

        
This code block in the floating window

Response-error

HTTP Status :400

// example of failed return results { "code": 35008, "message": "The contactListId does not exist" }
          // example of failed return results
{
    "code": 35008,
        "message": "The contactListId does not exist"
}

        
This code block in the floating window
在文档中心打开