Authorization

Access Token

Before making API calls, you need to fetch an access_token. Once you've done this, you include it with subsequent Reachify API requests as the Authorization HTTP request header. To generate an access_token, perform a GET request to the /auth endpoint, passing your API_KEY as an x-api-key header. You will need to obtain an API_KEY by contacting Reachify support.

To generate an access_token, perform this call:

curl "https://api.reachify.io/v1/auth" -H "x-api-key: YOUR_API_KEY"

Example response:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IllYQnBYMk55WldSbGJuUsfdnBZV3h6T2pJPSIsImlhdCI6MTUxNTQ1MTk3N30.blFY4nOs8LrE9iAizJtsHtxqCLtOYRjPDnzc_rHJ6e8",
    "status": "success"
}

Example request to the organization endpoint with access_token

curl "https://api.reachify.io/v1/organization" -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IllYQnBYMk55WldSbGJuUsfdnBZV3h6T2pJPSIsImlhdCI6MTUxNTQ1MTk3N30.blFY4nOs8LrE9iAizJtsHtxqCLtOYRjPDnzc_rHJ6e8"

Applications

An Application is the highest level object in the Reachify API. An Application may define custom branding for all child Enterprises and Organizations.

The Application Object

Field	Type	Description
id	string	Unique identifier
slug	string	Slug of Application, i.e. reachify
name	string	Name of Application, i.e. Reachify

Get Application

This endpoint returns your Application

Example request:

curl 'https://api.reachify.io/v1/application'

Example response:

    {
      "id": "application12345asdf67890ghijk" ,
      "slug": "sms",
      "name": "SMS",
    }

HTTP Request

GET https://api.reachify.io/v1/application

Enterprises

An Enterprise is the second highest level object in the Reachify API. If your API credentials are at the Application level, then you have the ability to create Enterprises. An Enterprise may define custom branding for all child Organizations. A typical use case of when Enterprises might be needed is when you are providing Reachify services to multiple businesses, where each business might have subsets of Organizations with shared custom branding.

The Enterprise Object

Field	Type	Description
id	string	Unique identifier
slug	string	Slug of enterprise
name	string	Name of enterprise

Get an Enterprise

This endpoint returns an Enterprise record.

Example request:

curl 'https://api.reachify.io/v1/enterprise/enterprise12345asdf67890ghijk'

Example response:

    {
      "id": "enterprise12345asdf67890ghijk" ,
      "slug": "evil-corp",
      "name": "Evil Corp",
    }

HTTP Request

GET https://api.reachify.io/v1/enterprise/{id}

List All Enterprises

This endpoint returns all Enterprise records

Example request:

curl 'https://api.reachify.io/v1/enterprise'

Example response:

    [
      {
        "id": "enterprise12345asdf67890ghijk" ,
        "slug": "evil-corp",
        "name": "Evil Corp",
      }
      ...
    ]

HTTP Request

GET https://api.reachify.io/v1/enterprise

Organizations

The Organization Object

Field	Type	Description
id	string	Unique identifier
slug	string	Slug of Organization
name	string	Name of Organization

Get an Organization

This endpoint returns an Organization record.

Example request:

curl 'https://api.reachify.io/v1/organization/organization12345asdf67890ghijk'

Example response:

    {
      "id": "organization12345asdf67890ghijk" ,
      "slug": "california-medical",
      "name": "California Medical",
    }

HTTP Request

GET https://api.reachify.io/v1/organization/{id}

List All Organizations

This endpoint returns all Organization records within the scope of your api access.

Example request:

curl 'https://api.reachify.io/organization'

Example response:

    [
      {
        "id": "organization12345asdf67890ghijk" ,
        "slug": "california-medical",
        "name": "California Medical",
      }
      ...
    ]

HTTP Request

GET https://api.reachify.io/v1/organization

Contacts

The Contact Object

Field	Type	Expandable	Description
id	string		Unique identifier
createdAt	timestamp with time zone		Timestamp of object creation
updatedAt	timestamp with time zone		Timestamp of last object update
version	integer		Version of object, initialized at 0 and incremented after each modification
firstName	string		First name
lastName	string		Last name
jobTitle	string		Job title
sex	male, female		Sex
dob	ISO string		Date of birth
metadata	JSON		Object containing custom metadata
creator	User	true	User who created this contact
details	array ContactDetails	true	Contact details (email addresses, phone numbers, etc...)

Create a contact

This endpoint creates a contact record.

Example request

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact',
  -d '
    {
      "organizationId": "b3JnYW5pemF0aW9uOjI=",
      "firstName": "James",
      "lastName": "Bond",
      "jobTitle": "Spy",
      "sex": "male",
      "dob": "2018-01-10T23:36:23.787Z",
      "details": [
        { "value": "+17604039282", "label": "home", "channels": ["voice", "sms"] },
        { "value": "[email protected]", "label": "work", "channels": ["email"] }
      ],
    }
  '

Example response

    {
      "id": "gsdf8143JKfsdkhjl" ,
      "firstName": "James",
      "lastName": "Bond",
      "jobTitle": "Spy",
      "sex": "male",
      "dob": "2018-01-10T23:36:23.787Z",
      "version": "0",
    }

Expanding on details would include the following fields in the response:

    {
      "details": [{
        "id": "12345asdf67890ghijk",
        "value": "+17604039282",
        "label": "home"
      }, {
        "id": "12345asdf67890ghijk",
        "value": "[email protected]",
        "label": "work"
      }],
    }

HTTP Request

POST https://api.reachify.io/v1/organization/{organizationId}/contact

Arguments

Parameter	Type	Required	Description
organizationId	string	true	Id of organization in which to create this contact
firstName	string	true	First name
lastName	string	true	Last name
jobTitle	string		Job title
creatorId	string		Id of user who created this contact
sex	male, female		Sex
dob	ISO string		Date of birth
metadata	JSON		Object containing custom metadata
details	array Details		Contact details

Details

Parameter	Type	Required	Description
label	string		Label of detail
value	string	true	Value of detail
channels	array string	true	An array of either channel ids or channel slugs, specifying the channels of this detail

Response

The response will be an object containing all of the fields of the Contact, including any expanded fields if specified

Update a contact

This endpoint updates a contact record.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact/12345asdf67890ghijk'
  -d '
    {
      "firstName": "James",
      "lastName": "Bond",
      "jobTitle": "Spy",
      "sex": "male",
      "dob": "2018-01-10T23:36:23.787Z",
    }
  '

Example response:

    {
      "id": "gsdf8143JKfsdkhjl" ,
      "firstName": "James",
      "lastName": "Bond",
      "jobTitle": "Spy",
      "version": "1",
      "sex": "male",
      "dob": "2018-01-10T23:36:23.787Z",
    }

HTTP Request

POST https://api.reachify.io/v1/organization/{organizationId}/contact/{id}

Arguments

Parameter	Type	Description
firstName	string	First name
lastName	string	Last name
jobTitle	string	Job title
sex	male, female	Sex
dob	ISO string	Date of birth
metadata	JSON	Object containing custom metadata

Response

The response will be an object containing all of the fields of the Contact, including any expanded fields if specified

Delete a contact

This endpoint updates a contact record. All associated contact data (details and addresses) will be deleted as well.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact/12345asdf67890ghijk',
  -X DELETE

Example response:

    {
      "deleted": true,
      "id": "12345asdf67890ghijk",
    }

HTTP Request

DELETE https://api.reachify.io/v1/organization/{organizationId}/contact/{id}

Response

The response will be an object containing the Contact id and a property deleted which will be set to true if the deletion was successful.

Get a Contact

This endpoint returns a Contact record.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact/contact12345asdf67890ghijk'

Example response:

  {
    "id": "contact12345asdf67890ghijk" ,
    "firstName": "James",
    "lastName": "Bond",
    "jobTitle": "Spy",
    "version": "0"
  }

HTTP Request

GET https://api.reachify.io/v1/organization/{organizationId}/contact/{id}

List All Contacts

This endpoint returns all Contact records

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact'

Example response:

    [
      {
        "id": "gsdf8143JKfsdkhjl" ,
        "firstName": "James",
        "lastName": "Bond",
        "jobTitle": "Spy",
        "version": "0"
      },
      ...
    ]

HTTP Request

GET https://api.reachify.io/v1/organization/{organizationId}/contact

Contact Details

The Contact Details Object

Field	Type	Expandable	Description
id	string		Unique identifier
createdAt	timestamp with time zone		Timestamp of object creation
updatedAt	timestamp with time zone		Timestamp of last object update
version	integer		Version of object, initialized at 0 and incremented after each modification
contactId	string		Id of contact
value	string		Details value
label	string		Details label
version	integer		Details label
channels	Channel	true	Channels in which this Contact Details value is valid. For example, if the value is an sms number, then the Contact Details would have an SMS channel.

Create Contact Details

This endpoint creates a contact details record.

Example request

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact-details'
  -d '
    {
      "contactId": "contact12345asdf67890ghijk",
      "value": "+17604039282",
      "label": "home",
      "channels": ["sms"]
    }
  '

Example response

    {
      "id": "contactDetails12345asdf67890ghijk" ,
      "contactId": "contact12345asdf67890ghijk",
      "label": "home",
      "value": "+17604039282",
      "version": "0"
    }

Expanding on channels would include the following fields in the response:

    {
      "channels": [{
        "id": "channel12345asdf67890ghijk",
        "slug": "sms",
      }],
    }

HTTP Request

POST https://api.reachify.io/v1/organization/{organizationId}/contact-details

Arguments

Parameter	Type	Required	Description
contactId	string	true	Id of contact to associate details with
value	string	true	Details value
label	string		Details label
channels	array string	true	An array of either channel ids or channel slugs, signifying the channels of this detail

Response

The response will be an object containing all of the fields of the Contact Details record, including any expanded fields if specified.

Update Contact Details

This endpoint updates a contact details record.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact-details/contactDetails12345asdf67890ghijk',
  -d '
    {
      "contactId": "contact12345asdf67890ghijk",
      "label": "work",
      "value": "+17604739682"
    }
  '

Example response:

    {
      "id": "contactDetails12345asdf67890ghijk" ,
      "contactId": "contact12345asdf67890ghijk",
      "label": "work",
      "value": "+17604739682",
      "version": "1"
    }

HTTP Request

POST https://api.reachify.io/v1/organization/{organizationId}/contact-details/{id}

Arguments

Parameter	Type	Description
contactId	string	Id of contact to associate details with
value	string	Details value
label	string	Details label
channels	array string	An array of either channel ids or channel slugs, signifying the channels of this detail

Response

The response will be an object containing all of the fields of the Contact Details record, including any expanded fields if specified

Delete Contact Details

This endpoint updates a contact details record.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact-details/contactDetails12345asdf67890ghijk',
  -X DELETE

Example response:

    {
      "deleted": true,
      "id": "12345asdf67890ghijk",
    }

HTTP Request

DELETE https://api.reachify.io/v1/organization/{organizationId}/contact-details/{id}

Response

The response will be an object containing the Contact Details id and a property deleted which will be set to true if the deletion was successful.

Get Contact Details

This endpoint returns a Contact Details record.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/contact-details/contactDetails12345asdf67890ghijk'

Example response:

  {
    "id": "contactDetails12345asdf67890ghijk" ,
    "contactId": "contact12345asdf67890ghijk",
    "label": "work",
    "value": "+17604739682",
    "version": "1"
  }

HTTP Request

GET https://api.reachify.io/v1/organization/{organizationId}/contact-details/{id}

Message

The Message Object

Field	Type	Description
id	string	Unique identifier
createdAt	timestamp with time zone	Timestamp of object creation
updatedAt	timestamp with time zone	Timestamp of last object update
body	string	Body of the message
direction	inbound, outbound	Direction of message transmission
from	string	Sender of message
to	string, array string	Recipients of message

Send a Message

This endpoint creates an SMS Message record and dispatches the Message to the desired recipients

Example request

curl -X POST 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/message',
  -d '
    {
      "body": "Hello there",
      "from": "18001234567",
      "to": [
        "17609876543"
      ]
    }
  '

Example response

    {
      "id": "12345asdf67890ghijk" ,
      "body": "Hello there",
      "from": "18001234567",
      "to": [
        "17609876543"
      ]
    }

HTTP Request

POST https://api.reachify.io/v1/organization/{organizationId}/message

Arguments

Parameter	Type	Required	Description
body	string	true	Body of the message
from	string	true	The phone number used to send the message
to	array string	true	Recipient phone numbers

Response

The response will be an object containing all of the base fields of the Message record.

Users

A User is an object with account credentials that may be used to login to one or more Organizations.

The User Object

Field	Type	Description
id	string	Unique identifier
createdAt	timestamp with time zone	Timestamp of object creation
updatedAt	timestamp with time zone	Timestamp of last object update
version	integer	Version of object, initialized at 0 and incremented after each modification
username	string	Username
firstName	string	First name
lastName	string	Last name
email	string	Account email address
password	string	Password hash (Only visible on initial user creation)
memberStatus	string	Member status

Create a user

This endpoint creates a user record. If password is not provided, one will be automatically generated and returned in the response.

Example request

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/user',
  -d '
    {
      "email": "[email protected]",
      "username": "james.bond",
      "firstName": "James",
      "lastName": "Bond",
    }
  '

Example response

    {
      "id": "user12345asdf67890ghijk" ,
      "email": "[email protected]",
      "username": "james.bond",
      "firstName": "James",
      "lastName": "Bond",
      "password": "thisIsAGeneratedPassword123",
      "memberStatus": "active",
      "version": "0",
    }

HTTP Request

POST https://api.reachify.io/v1/organization/{organizationId}/v1/user

Arguments

Parameter	Type	Required	Description
email	string	true	Email address
username	string		Username
firstName	string	true	First name
lastName	string	true	Last name
password	string		Password

Response

The response will be an object containing all of the fields of the User, including any expanded fields if specified

Update a user

This endpoint updates a user record.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/user/user12345asdf67890ghijk',
  -d '
    {
      "email": "[email protected]",
      "username": "james.bond",
      "firstName": "James",
      "lastName": "Bond",
      "memberStatus": "disabled",
    }
  '

Example response:

    {
      "id": "user12345asdf67890ghijk" ,
      "email": "[email protected]",
      "username": "james.bond",
      "firstName": "James",
      "lastName": "Bond",
      "memberStatus": "disabled",
      "version": "1",
    }

HTTP Request

POST https://api.reachify.io/v1/organization/{organizationId}/user/{id}

Arguments

Parameter	Type	Description
email	string	Email address
username	string	Username
firstName	string	First name
lastName	string	Last name
memberStatus	string [`active`,`disabled`]	Member status of user

Response

The response will be an object containing all of the fields of the User, including any expanded fields if specified

Delete a user

This endpoint deletes a user record.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/user/user12345asdf67890ghijk',
  -X DELETE

Example response:

    {
      "deleted": true,
      "id": "user12345asdf67890ghijk",
    }

HTTP Request

DELETE https://api.reachify.io/v1/organization/{organizationId}/user/{id}

Response

The response will be an object containing the User id and a property deleted which will be set to true if the deletion was successful.

Get a User

This endpoint returns a User record.

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/user/user12345asdf67890ghijk'

Example response:

  {
    "id": "user12345asdf67890ghijk" ,
    "email": "[email protected]",
    "username": "james.bond",
    "firstName": "James",
    "lastName": "Bond",
    "version": "0",
  }

HTTP Request

GET https://api.reachify.io/v1/organization/{organizationId}/user/{id}

List All Users

This endpoint returns all User records within an organization

Example request:

curl 'https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/user'

Example response:

    [
      {
        "id": "user12345asdf67890ghijk" ,
        "email": "[email protected]",
        "username": "james.bond",
        "firstName": "James",
        "lastName": "Bond",
        "version": "0",
      },
      ...
    ]

HTTP Request

GET https://api.reachify.io/v1/organization/{organizationId}/user

Interactions

This endpoint will provide you with a list of interactions associated with the given email(s) and phone number(s).

Parameter	Type	Description
values	string	Single value, or comma-delimited list of values to search for interactions
contactId	string	Contact id to search for interactions
pageNumber	integer	Page of results to start on
pageSize	integer	Number of results per page

Interaction

Key	Type	Description
timestamp	timestamp with time zone	Timestamp of object creation
channel	string	Channel of conversation ('email', 'sms', etc...)
link	string	Link to conversation

To get the related interactions for [email protected], perform this call:

curl "https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/[email protected]" -H "x-api-key: YOUR_API_KEY"

Example response:

{
    "interactions": [
      {
        timestamp: "2021-02-01T21:42:13.900Z",
        channel: "email",
        link: "https://your-org.app.reachify.io/inbox/1jgldDCJB35B/YW5pemF0aW9"
      }
    ]
    "pageNumber": 1,
    "totalPages": 1,
}

To get the first page of related interactions for [email protected] and +17603346948, with a page size of 3, perform this call:

curl "https://api.reachify.io/v1/organization/b3JnYW5pemF0aW9uOjI/[email protected],+17603346948&pageSize=3" -H "x-api-key: YOUR_API_KEY"

Example response:

{
    "interactions": [
      {
        timestamp: "2021-02-01T21:42:13.900Z",
        channel: "email",
        link: "https://your-org.app.reachify.io/inbox/1jgldDCJB35B/YW5pemF0aW9"
      },
      {
        timestamp: "2021-01-01T21:42:13.900Z",
        channel: "sms",
        link: "https://your-org.app.reachify.io/inbox/1jgldDCJB35B/YW5pembjco426j"
      },
      {
        timestamp: "2020-12-01T21:42:13.900Z",
        channel: "sms",
        link: "https://your-org.app.reachify.io/inbox/1jgldDCJB35B/YW5pemF031dkw"
      }
    ]
    "pageNumber": 1,
    "totalPages": 2,
}

You may provide a token query parameter to your url to automatically log a user in. This can be done by making a request to the /v1/login-token endpoint with the following query parameters:

Parameter	Type	Description
userId	string	Id of the user to login
organizationId	string	Id of the organization which the user belongs to
apikey	string	Your api key

Example request:

curl -XGET https://api.reachify.io/v1/login-token?userId=123456asdfgjk&organizationId=asdfgj123456&apikey=e074d7d9468648b1863460f2003bgdkcj

This will return a token, which you can append to any reachify url to automatically log the user in:

.../inbox?token=978qpuibvpoirWEIbpiW8sdf6g89.dfg7WEccoppiqnelkiuvoui

Authorization

Access Token

Applications

The Application Object

Get Application

HTTP Request

Enterprises

The Enterprise Object

Get an Enterprise

HTTP Request

List All Enterprises

HTTP Request

Organizations

The Organization Object

Get an Organization

HTTP Request

List All Organizations

HTTP Request

Contacts

The Contact Object

Create a contact

HTTP Request

Arguments

Details

Response

Update a contact

HTTP Request

Arguments

Response

Delete a contact

HTTP Request

Response

Get a Contact

HTTP Request

List All Contacts

HTTP Request

Contact Details

The Contact Details Object

Create Contact Details

HTTP Request

Arguments

Response

Update Contact Details

HTTP Request

Arguments

Response

Delete Contact Details

HTTP Request

Response

Get Contact Details

HTTP Request

Message

The Message Object

Send a Message

HTTP Request

Arguments

Response

Users

The User Object

Create a user

HTTP Request

Arguments

Response

Update a user

HTTP Request

Arguments

Response

Delete a user

HTTP Request

Response

Get a User

HTTP Request

List All Users

HTTP Request

Interactions

Fetching Related Interactions

Interaction

Auto Login