Contacts

Creates a contact under a client, or a temporary contact when no client is given.

With a ClientId the contact belongs to that client. Without one it is created as a temporary contact (IsTemporaryContact true) with no client and no location - the kind of contact an email from an unknown requester creates - and it can be used as the contact or a cc contact on a ticket that has no client. A LocationId needs a ClientId.

If another contact, active or temporary, already has the primary email address, nothing is created and the response is a 409 whose message carries that contact’s id: use it rather than retrying. This endpoint never updates an existing contact.

POST

contacts

curl --request POST \
  --url https://api.usw.gorelo.io/v1/contacts \
  --header 'Content-Type: application/json-patch+json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "FirstName": "Jane",
  "LastName": "Doe",
  "PrimaryEmail": "jane.doe@contoso.com",
  "ClientId": 123,
  "LocationId": 123,
  "SecondaryEmail": [
    "<string>"
  ],
  "MobilePhone": "<string>",
  "MobilePhoneCountryCode": "<string>",
  "OfficePhone": "<string>",
  "OfficePhoneCountryCode": "<string>",
  "JobTitle": "<string>",
  "Department": "<string>",
  "TimeZone": "<string>",
  "Description": "<string>"
}
'

import requests

url = "https://api.usw.gorelo.io/v1/contacts"

payload = {
    "FirstName": "Jane",
    "LastName": "Doe",
    "PrimaryEmail": "jane.doe@contoso.com",
    "ClientId": 123,
    "LocationId": 123,
    "SecondaryEmail": ["<string>"],
    "MobilePhone": "<string>",
    "MobilePhoneCountryCode": "<string>",
    "OfficePhone": "<string>",
    "OfficePhoneCountryCode": "<string>",
    "JobTitle": "<string>",
    "Department": "<string>",
    "TimeZone": "<string>",
    "Description": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    FirstName: 'Jane',
    LastName: 'Doe',
    PrimaryEmail: 'jane.doe@contoso.com',
    ClientId: 123,
    LocationId: 123,
    SecondaryEmail: ['<string>'],
    MobilePhone: '<string>',
    MobilePhoneCountryCode: '<string>',
    OfficePhone: '<string>',
    OfficePhoneCountryCode: '<string>',
    JobTitle: '<string>',
    Department: '<string>',
    TimeZone: '<string>',
    Description: '<string>'
  })
};

fetch('https://api.usw.gorelo.io/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usw.gorelo.io/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'FirstName' => 'Jane',
    'LastName' => 'Doe',
    'PrimaryEmail' => 'jane.doe@contoso.com',
    'ClientId' => 123,
    'LocationId' => 123,
    'SecondaryEmail' => [
        '<string>'
    ],
    'MobilePhone' => '<string>',
    'MobilePhoneCountryCode' => '<string>',
    'OfficePhone' => '<string>',
    'OfficePhoneCountryCode' => '<string>',
    'JobTitle' => '<string>',
    'Department' => '<string>',
    'TimeZone' => '<string>',
    'Description' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json-patch+json",
    "X-API-Key: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usw.gorelo.io/v1/contacts"

	payload := strings.NewReader("{\n  \"FirstName\": \"Jane\",\n  \"LastName\": \"Doe\",\n  \"PrimaryEmail\": \"jane.doe@contoso.com\",\n  \"ClientId\": 123,\n  \"LocationId\": 123,\n  \"SecondaryEmail\": [\n    \"<string>\"\n  ],\n  \"MobilePhone\": \"<string>\",\n  \"MobilePhoneCountryCode\": \"<string>\",\n  \"OfficePhone\": \"<string>\",\n  \"OfficePhoneCountryCode\": \"<string>\",\n  \"JobTitle\": \"<string>\",\n  \"Department\": \"<string>\",\n  \"TimeZone\": \"<string>\",\n  \"Description\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usw.gorelo.io/v1/contacts")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"FirstName\": \"Jane\",\n  \"LastName\": \"Doe\",\n  \"PrimaryEmail\": \"jane.doe@contoso.com\",\n  \"ClientId\": 123,\n  \"LocationId\": 123,\n  \"SecondaryEmail\": [\n    \"<string>\"\n  ],\n  \"MobilePhone\": \"<string>\",\n  \"MobilePhoneCountryCode\": \"<string>\",\n  \"OfficePhone\": \"<string>\",\n  \"OfficePhoneCountryCode\": \"<string>\",\n  \"JobTitle\": \"<string>\",\n  \"Department\": \"<string>\",\n  \"TimeZone\": \"<string>\",\n  \"Description\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usw.gorelo.io/v1/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n  \"FirstName\": \"Jane\",\n  \"LastName\": \"Doe\",\n  \"PrimaryEmail\": \"jane.doe@contoso.com\",\n  \"ClientId\": 123,\n  \"LocationId\": 123,\n  \"SecondaryEmail\": [\n    \"<string>\"\n  ],\n  \"MobilePhone\": \"<string>\",\n  \"MobilePhoneCountryCode\": \"<string>\",\n  \"OfficePhone\": \"<string>\",\n  \"OfficePhoneCountryCode\": \"<string>\",\n  \"JobTitle\": \"<string>\",\n  \"Department\": \"<string>\",\n  \"TimeZone\": \"<string>\",\n  \"Description\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": {
    "Id": 123,
    "FirstName": "<string>",
    "LastName": "<string>",
    "Status": {
      "Id": 1,
      "Name": "<string>"
    },
    "ClientId": 123,
    "LocationId": 123,
    "CreatedOn": "2023-11-07T05:31:56Z",
    "UpdatedOn": "2023-11-07T05:31:56Z",
    "PrimaryEmail": "<string>",
    "Alias": "<string>",
    "MobilePhone": "<string>",
    "MobilePhoneCountryCode": "<string>",
    "OfficePhone": "<string>",
    "OfficePhoneCountryCode": "<string>",
    "JobTitle": "<string>",
    "Department": "<string>",
    "TimeZone": "<string>",
    "Description": "<string>",
    "IsTemporaryContact": true,
    "MergedWithContactId": 123
  },
  "DataContext": null,
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

Authorizations

X-API-Key

string

header

required

Your Gorelo API key. See Generate API key. If your data is hosted in Australia, click the base URL at the top of this page and select https://api.aue.gorelo.io.

Body

Contact details.

Request body for creating a contact, under a client or, with no client, as a temporary contact.

FirstName

string

required

Contact first name. Required. Maximum 150 characters.

Minimum string length: 1

Example:

"Jane"

LastName

string

required

Contact last name. Required. Maximum 150 characters.

Minimum string length: 1

Example:

"Doe"

PrimaryEmail

string

required

Primary email address. Required. Maximum 200 characters.

Minimum string length: 1

Example:

"jane.doe@contoso.com"

ClientId

integer<int64> | null

Identifier of the client the contact belongs to. Optional. When omitted the contact is created as a temporary contact (IsTemporaryContact true) with no client, the way an email from an unknown requester creates one; a temporary contact can be the contact or a cc contact on a ticket that has no client.

LocationId

integer<int64> | null

Identifier of the client location the contact belongs to. Requires ClientId.

SecondaryEmail

string[] | null

Additional (secondary) email addresses. Maximum 200 characters each.

MobilePhone

string

Mobile phone number, as dialled within its country, e.g. 021 123 4567 for NZ; an international +64 21 123 4567 is accepted too. A number sent without its leading 0 (21 123 4567) is stored with it. Maximum 20 characters.

MobilePhoneCountryCode

string

Mobile phone ISO 3166-1 alpha-2 region code (e.g. US). Maximum 100 characters.

OfficePhone

string

Office phone number, as dialled within its country, e.g. 021 123 4567 for NZ; an international +64 21 123 4567 is accepted too. A number sent without its leading 0 (21 123 4567) is stored with it. Maximum 20 characters.

OfficePhoneCountryCode

string

Office phone ISO 3166-1 alpha-2 region code (e.g. US). Maximum 25 characters.

JobTitle

string

Contact job title. Maximum 100 characters.

Department

string

Contact department. Maximum 150 characters.

TimeZone

string

IANA time zone identifier for the contact (e.g. America/New_York). Maximum 50 characters.

Description

string

Free-text description / notes for the contact. Maximum 2000 characters.

Response

StatusCode

enum<integer>

Available options:

100,

101,

102,

103,

200,

201,

202,

203,

204,

205,

206,

207,

208,

226,

300,

301,

302,

303,

304,

305,

306,

307,

308,

400,

401,

402,

403,

404,

405,

406,

407,

408,

409,

410,

411,

412,

413,

414,

415,

416,

417,

421,

422,

423,

424,

426,

428,

429,

431,

451,

500,

501,

502,

503,

504,

505,

506,

507,

508,

510,

511

IsSuccess

boolean

Data

object

A contact belonging to a client. Timestamps are UTC.

Show child attributes

DataContext

object | null

Example:

null

Notifications

object[]

Show child attributes

⌘I

Creates a contact under a client, or a temporary contact when no client is given.

curl --request POST \
  --url https://api.usw.gorelo.io/v1/contacts \
  --header 'Content-Type: application/json-patch+json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "FirstName": "Jane",
  "LastName": "Doe",
  "PrimaryEmail": "jane.doe@contoso.com",
  "ClientId": 123,
  "LocationId": 123,
  "SecondaryEmail": [
    "<string>"
  ],
  "MobilePhone": "<string>",
  "MobilePhoneCountryCode": "<string>",
  "OfficePhone": "<string>",
  "OfficePhoneCountryCode": "<string>",
  "JobTitle": "<string>",
  "Department": "<string>",
  "TimeZone": "<string>",
  "Description": "<string>"
}
'

import requests

url = "https://api.usw.gorelo.io/v1/contacts"

payload = {
    "FirstName": "Jane",
    "LastName": "Doe",
    "PrimaryEmail": "jane.doe@contoso.com",
    "ClientId": 123,
    "LocationId": 123,
    "SecondaryEmail": ["<string>"],
    "MobilePhone": "<string>",
    "MobilePhoneCountryCode": "<string>",
    "OfficePhone": "<string>",
    "OfficePhoneCountryCode": "<string>",
    "JobTitle": "<string>",
    "Department": "<string>",
    "TimeZone": "<string>",
    "Description": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    FirstName: 'Jane',
    LastName: 'Doe',
    PrimaryEmail: 'jane.doe@contoso.com',
    ClientId: 123,
    LocationId: 123,
    SecondaryEmail: ['<string>'],
    MobilePhone: '<string>',
    MobilePhoneCountryCode: '<string>',
    OfficePhone: '<string>',
    OfficePhoneCountryCode: '<string>',
    JobTitle: '<string>',
    Department: '<string>',
    TimeZone: '<string>',
    Description: '<string>'
  })
};

fetch('https://api.usw.gorelo.io/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usw.gorelo.io/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'FirstName' => 'Jane',
    'LastName' => 'Doe',
    'PrimaryEmail' => 'jane.doe@contoso.com',
    'ClientId' => 123,
    'LocationId' => 123,
    'SecondaryEmail' => [
        '<string>'
    ],
    'MobilePhone' => '<string>',
    'MobilePhoneCountryCode' => '<string>',
    'OfficePhone' => '<string>',
    'OfficePhoneCountryCode' => '<string>',
    'JobTitle' => '<string>',
    'Department' => '<string>',
    'TimeZone' => '<string>',
    'Description' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json-patch+json",
    "X-API-Key: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usw.gorelo.io/v1/contacts"

	payload := strings.NewReader("{\n  \"FirstName\": \"Jane\",\n  \"LastName\": \"Doe\",\n  \"PrimaryEmail\": \"jane.doe@contoso.com\",\n  \"ClientId\": 123,\n  \"LocationId\": 123,\n  \"SecondaryEmail\": [\n    \"<string>\"\n  ],\n  \"MobilePhone\": \"<string>\",\n  \"MobilePhoneCountryCode\": \"<string>\",\n  \"OfficePhone\": \"<string>\",\n  \"OfficePhoneCountryCode\": \"<string>\",\n  \"JobTitle\": \"<string>\",\n  \"Department\": \"<string>\",\n  \"TimeZone\": \"<string>\",\n  \"Description\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usw.gorelo.io/v1/contacts")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"FirstName\": \"Jane\",\n  \"LastName\": \"Doe\",\n  \"PrimaryEmail\": \"jane.doe@contoso.com\",\n  \"ClientId\": 123,\n  \"LocationId\": 123,\n  \"SecondaryEmail\": [\n    \"<string>\"\n  ],\n  \"MobilePhone\": \"<string>\",\n  \"MobilePhoneCountryCode\": \"<string>\",\n  \"OfficePhone\": \"<string>\",\n  \"OfficePhoneCountryCode\": \"<string>\",\n  \"JobTitle\": \"<string>\",\n  \"Department\": \"<string>\",\n  \"TimeZone\": \"<string>\",\n  \"Description\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usw.gorelo.io/v1/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n  \"FirstName\": \"Jane\",\n  \"LastName\": \"Doe\",\n  \"PrimaryEmail\": \"jane.doe@contoso.com\",\n  \"ClientId\": 123,\n  \"LocationId\": 123,\n  \"SecondaryEmail\": [\n    \"<string>\"\n  ],\n  \"MobilePhone\": \"<string>\",\n  \"MobilePhoneCountryCode\": \"<string>\",\n  \"OfficePhone\": \"<string>\",\n  \"OfficePhoneCountryCode\": \"<string>\",\n  \"JobTitle\": \"<string>\",\n  \"Department\": \"<string>\",\n  \"TimeZone\": \"<string>\",\n  \"Description\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": {
    "Id": 123,
    "FirstName": "<string>",
    "LastName": "<string>",
    "Status": {
      "Id": 1,
      "Name": "<string>"
    },
    "ClientId": 123,
    "LocationId": 123,
    "CreatedOn": "2023-11-07T05:31:56Z",
    "UpdatedOn": "2023-11-07T05:31:56Z",
    "PrimaryEmail": "<string>",
    "Alias": "<string>",
    "MobilePhone": "<string>",
    "MobilePhoneCountryCode": "<string>",
    "OfficePhone": "<string>",
    "OfficePhoneCountryCode": "<string>",
    "JobTitle": "<string>",
    "Department": "<string>",
    "TimeZone": "<string>",
    "Description": "<string>",
    "IsTemporaryContact": true,
    "MergedWithContactId": 123
  },
  "DataContext": null,
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}