Last updated on Sep 4
5 min read
Contacts API
Samespace provides an API to manage contacts in your Samespace account. With this API, you can create, delete, and update contacts.
GraphQL Endpoint & Header Details
| Endpoint | https://clusterid.samespace.com/crm/api |
|---|---|
| x-api-key | XoaFDQ34c@NIs!AvGgCYe2jmCppr43FR |
Note: For the Contacts API to work, an API key with type “Voice” is required. Only users with "Admin" access can create the same in the settings section.
Get Contacts
This API enables users to get a list of contacts created in their Samespace account.
Query
query GetContacts($module: ID, $moduleName: String, $query: QueryInput) {
getContacts(module: $module, moduleName: $moduleName, query: $query) {
_id
properties
module
}
}
Payload
{
"query": {
"skip": 0,
"fields": [
"firstName",
"lastName",
"phoneNumber",
"company"
],
"limit": 50
},
"module": "6303289128a0e96163bd0dcd"
}
Response
{
"data": {
"getContacts": [
{
"_id": "639ffb55f6157c6ca7d39fb6",
"module": "6303289128a0e96163bd0dcd",
"properties": {
"firstName": {
"value": "Kris",
"type": "TEXT"
},
"lastName": {
"value": "Merrier",
"type": "TEXT"
},
"email": {
"value": "[email protected]",
"type": "EMAIL"
},
"phoneNumber": {
"value": "555-555-5555",
"type": "PHONE"
},
"owner": {
"value": "62da90cb9fcc0cfec12a2d80",
"type": "REFERENCE"
},
"createdBy": {
"value": "62da90cb9fcc0cfec12a2d80",
"type": "REFERENCE"
},
"createdAt": {
"value": "2022-12-19T05:49:09.557Z",
"type": "DATE_TIME"
}
}
}
]
}
}
Create Contacts
This Open API enables you to create contacts.
Mutation
mutation CreateContact($properties: [KeyValueInput!]!, $module: ID, $moduleName: String) {
createContact(properties: $properties, module: $module, moduleName: $moduleName) {
_id
}
}
Payload
{
"module": "6303289128a0e96163bd0dcd",
"properties": [
{
"key": "firstName",
"value": "Alan"
},
{
"key": "lastName",
"value": "Wilkins"
},
{
"key": "email",
"value": "[email protected]"
}
]
}
Response
{
"data": {
"createContact": {
"_id": "649573e2a92124d90619988b"
}
}
}
Update Contacts
The API uses the Contact ID to update a single contact’s details.
Mutation
mutation UpdateContacts($properties: [KeyValueInput!]!, $module: ID, $id: [ID!], $filter: JSON, $all: Boolean, $moduleName: String) {
updateContacts(
properties: $properties
module: $module
_id: $id
filter: $filter
all: $all
moduleName: $moduleName
)
}
Payload
{
"module": "6303289128a0e96163bd0dcd",
"id": "649573e2a92124d90619988b",
"properties": [
{
"key": "phoneNumber",
"value": "919852234732"
}
]
}
Response
{
"data": {
"updateContacts": {
"success": true,
"message": "Contact updated"
}
}
}
Delete Contacts
This API is used to delete multiple contacts.
Mutation
mutation DeleteContacts($module: ID, $moduleName: String, $id: [ID!], $filter: JSON, $all: Boolean) {
deleteContacts(
module: $module
moduleName: $moduleName
_id: $id
filter: $filter
all: $all
)
}
Payload
{
"module": "6303289128a0e96163bd0dcd",
"id": [
"64c0baf2a4286adebf197984"
]
}
Response
{
"data": {
"deleteContacts": {
"success": true,
"message": "Contact deleted"
}
}
}
Get Modules
Query
query GetModules {
getModules {
_id
name
createdAt
modifiedAt
}
}
Response
{
"data": {
"getModules": [
{
"_id": "6303289128a0e96163bd0dcd",
"name": "Contacts",
"createdAt": "1680874752505",
"modifiedAt": "1680874752505"
}
]
}
}
Get Properties
The purpose of this API is to retrieve a list of fields that are associated with contacts.
Query
query GetProperties($module: ID, $moduleName: String, $payload: GetPropertiesInput) {
getProperties(module: $module, moduleName: $moduleName, payload: $payload) {
_id
label
key
type
options {
label
key
}
optionsType
referenceModule
addToView
displayOrder
required
valueType
default
createdBy
}
}
Payload
{
"module": "6303289128a0e96163bd0dcd",
"payload": {
"query": {
"skip": 0,
"limit": 2
}
}
}
Response
{
"data": {
"getProperties": [
{
"_id": "641466b0624d8c8b93becd69",
"label": "First Name",
"key": "firstName",
"type": "TEXT",
"options": null,
"optionsType": null,
"referenceModule": null,
"addToView": true,
"displayOrder": 1,
"required": true,
"valueType": null,
"default": false,
"createdBy": null
},
{
"_id": "641466b0624d8c8b93becd6a",
"label": "Last Name",
"key": "lastName",
"type": "TEXT",
"options": null,
"optionsType": null,
"referenceModule": null,
"addToView": true,
"displayOrder": 2,
"required": true,
"valueType": null,
"default": false,
"createdBy": null
}
]
}
}
Create Property
This API enables you to create customizable attributes in your contacts that can be utilized according to your specific requirements.
Query
mutation CreateProperty($payload: CreatePropertyInput!, $module: ID, $moduleName: String) {
createProperty(payload: $payload, module: $module, moduleName: $moduleName) {
_id
label
key
type
options {
label
key
}
optionsType
referenceModule
addToView
displayOrder
required
valueType
default
createdBy
}
}
Payload
{
"module": "6303289128a0e96163bd0dcd",
"payload": {
"label": "Notes",
"type": "TEXT",
"description": null,
"options": null,
"optionsSortBy": null,
"optionsType": null,
"required": false,
"addToView": false,
"valueType": "STRING",
"referenceModule": null
}
}
Response
{
"data": {
"createProperty": {
"_id": "64958063a92124d90619988e",
"label": "Notes",
"key": "notes",
"type": "TEXT",
"options": null,
"optionsType": null,
"referenceModule": null,
"addToView": false,
"displayOrder": 25,
"required": false,
"valueType": "STRING",
"default": false,
"createdBy": "6384a0855fab959a1618e103"
}
}
}
Update a Property
Query
mutation UpdateProperty($id: ID!, $payload: UpdatePropertyInput!, $module: ID, $moduleName: String) {
updateProperty(
_id: $id
payload: $payload
module: $module
moduleName: $moduleName
) {
_id
addToView
default
description
displayOrder
key
label
required
type
createdBy
}
}
Payload
{
"module": "6303289128a0e96163bd0dcd",
"id": "64958063a92124d90619988e",
"payload": {
"description": "This property is used to take down notes by the agent"
}
}
Response
{
"data": {
"updateProperty": {
"_id": "64958063a92124d90619988e",
"description": "This property is used to take down notes by the agent",
"displayOrder": 25,
"key": "notes",
"label": "Notes",
"type": "TEXT",
"createdBy": "6384a0855fab959a1618e103"
}
}
}
csv/xls Upload
This REST API serves the purpose of bulk uploading a list of contacts into Samespace. The accepted file formats for this purpose are either CSV or XLS.
| Endpoint | https://clusterid.samespace.com/manage/api/v3/csv/upload |
Header
Content-Type: multipart/form-data
Body
uploadFile=<file>
Response
{
"fileUuid": "49f88e98-1fb1-493e-b48a-1e9aa6dc838f",
"filename": "Samespace - Members.csv",
"columns": [
"firstname",
"lastname",
"email",
"phonenumber",
"cluster"
],
"preview": {
"firstname": "Abhishek",
"lastname": "Kambli",
"email": "[email protected]",
"phonenumber": "16468107050",
"cluster": "Samespace"
}
}
Now take the "fileUuid" from the above response and use it in the paayload of the below API to map the columns of the uploaded file
Query
mutation ImportContacts($fileUuid: String!, $mapAttributes: [KeyValueInput!]!, $module: ID, $moduleName: String) {
importContacts(
fileUuid: $fileUuid
mapAttributes: $mapAttributes
module: $module
moduleName: $moduleName
)
}
Payload
{
"module": "6303289128a0e96163bd0dcd",
"fileUuid": "49f88e98-1fb1-493e-b48a-1e9aa6dc838f",
"mapAttributes": [
{
"value": "firstName",
"key": "firstname"
},
{
"value": "lastName",
"key": "lastname"
},
{
"value": "email",
"key": "email"
},
{
"value": "phoneNumber",
"key": "phonenumber"
}
]
}
Response
{
"data": {
"importContacts": {
"success": 28,
"failed": [
{
"contact": {
"firstName": "Neha",
"lastName": "Chandanshive",
"email": "[email protected]",
"phoneNumber": "16468107050"
},
"reason": "Invalid \"Contact Owner\" input",
"key": "email"
},
],
"merged": 6
}
}
}
The response will provide information on the number of contacts successfully added, identify contacts that failed to upload, and perform duplicate contact merging.