Please be aware there is a known issue with images on the Community. We are working to resolve this issue as quickly as possible. We apologize for the inconvenience. If you need urgent help in the meantime, please reach out to technical support or your Threekit representative.

  1. Threekit
  2. Developer
  3. Connecting and Displaying Externally (APIs)
  4. APIs

Customers API

In this article

GET https://admin.threekit.com/api/customers

Retrieves the list of customers. The list will contain all customers from the token's organization. For each entry the following information will be available.

  1. id - Customer ID
  2. orgId - Organization ID
  3. name - Customer Name (If present)
  4. position - Customer Position (If present)
  5. city - Customer City (If present)
  6. country - Customer Country (If present)
  7. company - Customer Company (If present)
  8. email - Customer Email (If present)
  9. phone - Customer Phone Number (If present)
  10. ip - Customer IP Address (If present)
  11. metadata - Metadata (If present)
  12. platform - Platform (If present)
  13. address - Customer Address (If present)
  14. createdAt - The time when this customer was created

REST Endpoint

GET https://admin.threekit.com/api/customers?bearer_token=[bearer_token]&orgId=[orgId]&platform=[platform]

Query Parameters

Name In Type Required Description
bearer_token query string false Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token. A public token has read-only permissions whereas a private token has read and write permissions.
orgId query string false Organization ID.
platform query string false Retrieve customers by platform data. Must be passed in as a stringified JSON.

Response Codes

Status Meaning Description Schema
200 OK Successful get request, response body will include the list of customers None
401 Unauthorized The token provided is not authorized to make the request or the token is invalid. None
403 Forbidden No token was provided in the query string of the request, or a public token was used to try and create a customer None

Example Implementations

Code

CURL
curl --request GET \
  --url https://admin.threekit.com/api/customers \
  --header 'authorization: Bearer {access-token}'
Node.JS
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/customers",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

{
  "customers": [
    {
      "id": "d07d085d-41a6-445b-9b10-b588387ecada",
      "orgId": "ef9dc95d-2c04-4052-b615-c28b97a12ebe",
      "name": "Example Name",
      "position": "Example Position",
      "city": "Example City",
      "country": "Example Country",
      "company": "Example Company",
      "email": "example@example.com",
      "phone": "1111111111",
      "ip": "127.0.0.1",
      "metadata": {
        "orders": 5
      },
      "platform": {
        "shopify": "exampleID"
      },
      "createdAt": "2020-03-13T19:54:53.779Z"
    },
    {
      "id": "42cfb0b3-1312-47fd-84fa-4980893f9868",
      "orgId": "ef9dc95d-2c04-4052-b615-c28b97a12ebe",
      "name": "Example Name",
      "position": "Example Position",
      "city": "Example City",
      "country": "Example Country",
      "company": "Example Company",
      "email": "example@example.com",
      "phone": "9999999999",
      "ip": "120.0.0.1",
      "metadata": {
        "orders": 6
      },
      "platform": {
        "shopify": "exampleID"
      },
      "createdAt": "2020-03-13T19:58:19.367Z"
    }
  ]
}

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "forbidden"
  }
}

POST https://admin.threekit.com/api/customers

Creates a customer and generates an UUID which can be used to retrieve the customer.

REST Endpoint

POST https://admin.threekit.com/api/customers?bearer_token=[bearer_token]

Query Parameters

Name In Type Required Description
bearer_token query string false Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token. A public token has read-only permissions whereas a private token has read and write permissions.
body body createBody true Customer information.

Body Parameters

{
  "name": "string",
  "orgId": "string",
  "position": "string",
  "city": "string",
  "country": "string",
  "email": "string",
  "phone": "string",
  "ip": "string",
  "metadata": {},
  "platform": "{ExamplePlatformName: ExamplePlatformCustomerId}",
  "address": "string"
}

Response Codes

Status Meaning Description Schema
200 OK Returns a customer and its information None
401 Unauthorized The token provided is not authorized to make the request or the token is invalid. None
403 Forbidden No token was provided in the query string of the request, or a public token was used to try and create a customer None

Example Implementations

Code

CURL
curl --request POST \
  --url https://admin.threekit.com/api/customers \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data '{"name":"string","orgId":"string","position":"string","city":"string","country":"string","email":"string","phone":"string","ip":"string","metadata":{},"platform":"{ExamplePlatformName: ExamplePlatformCustomerId}","address":"string"}'
Node.JS
var http = require("https");

var options = {
  "method": "POST",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/customers",
  "headers": {
    "content-type": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  name: 'string',
  orgId: 'string',
  position: 'string',
  city: 'string',
  country: 'string',
  email: 'string',
  phone: 'string',
  ip: 'string',
  metadata: {},
  platform: '{ExamplePlatformName: ExamplePlatformCustomerId}',
  address: 'string'
}));
req.end();
PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"name\":\"string\",\"orgId\":\"string\",\"position\":\"string\",\"city\":\"string\",\"country\":\"string\",\"email\":\"string\",\"phone\":\"string\",\"ip\":\"string\",\"metadata\":{},\"platform\":\"{ExamplePlatformName: ExamplePlatformCustomerId}\",\"address\":\"string\"}",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

{
  "id": "b6ed7591-bffa-4f2a-9c0a-5b823c9e1385",
  "orgId": "94d4219e-f70b-4112-9ff8-e8ceeeb20491",
  "name": "Example Name",
  "position": "Example Position",
  "city": "Example City",
  "country": "Example Country",
  "company": "Example Company",
  "email": "example@example.com",
  "phone": "1111111111",
  "ip": "127.0.0.1",
  "metadata": {
    "orders": 5
  },
  "platform": {
    "examplePlatform": "exampleID"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "forbidden"
  }
}

GET https://admin.threekit.com/api/customers/{id}

Retrieves a customer from its ID. Only works for customers belonging to the token's organization.

REST Endpoint

GET https://admin.threekit.com/api/customers/{id}?bearer_token=[bearer_token]

Query Parameters

Name In Type Required Description
id path string true ID of the customer to be retrieved
bearer_token query string false Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token. A public token has read-only permissions whereas a private token has read and write permissions.

Response Codes

Status Meaning Description Schema
200 OK Returns a customer and its information None
401 Unauthorized The token provided is not authorized to make the request or the token is invalid. None
403 Forbidden User provides the ID of a customer which is not set to be publically shared. None
404 Not Found No customer was found for the given ID None

Example Implementations

Code

CURL
curl --request GET \
  --url https://admin.threekit.com/api/customers/string \
  --header 'authorization: Bearer {access-token}'
Node.JS
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/customers/string",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/customers/string",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

{
  "id": "32742082-63d8-4ba8-9c18-d06112b720e9",
  "orgId": "c072dfa9-bb3b-4958-87f7-08a3160c32ca",
  "name": "Example Name",
  "position": "Example Position",
  "city": "Example Ottawa",
  "country": "Example Canada",
  "company": "Example Company",
  "email": "example@example.com",
  "phone": "9999999999",
  "ip": "120.0.0.1",
  "metadata": {
    "orders": 6
  },
  "platform": {
    "examplePlatform": "exampleID"
  },
  "createdAt": "2020-03-13T19:58:19.367Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

{
  "error": {
    "type": "forbidden",
    "message": "forbidden"
  }
}

{
  "error": {
    "type": "customer_not_found_error",
    "message": "Customer not found"
  }
}

Schemas

createBody

{
  "name": "string",
  "orgId": "string",
  "position": "string",
  "city": "string",
  "country": "string",
  "email": "string",
  "phone": "string",
  "ip": "string",
  "metadata": {},
  "platform": "{ExamplePlatformName: ExamplePlatformCustomerId}",
  "address": "string"
}

Properties

Name Type Required Restrictions Description
name string false none Name of the customer.
orgId string false none ID of the organization.
position string false none Position of the customer.
city string false none City of the customer.
country string false none Country of the customer.
email string false none Email of the customer.
phone string false none Phone number of the customer.
ip string false none IP address of the customer.
metadata object false none Metadata related to the customer.
platform object false none Platform details related to the customer. It can only contain 1 key-value pair.
address string false none Address of the customer. The maximum number of characters allow for an address is 1000 characters.
Was this article helpful? Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles

Powered by Zendesk