Authentication

Client Heartbeat's JSON API uses OAuth 2 to enable API Authentication.

If you'd like to get started with our API, get in touch with us and we'll help organise the required public and private keys.

Client Heartbeat also provides renew tokens for OAuth, allowing you to persist your users authentication session.

For more information about OAuth 2, including some examples you can check the OAuth site. We also have some examples on GitHub.

Authorize URL: https://clientheartbeat.com/oauth/authorize
Example Authorize URI: 
https://clientheartbeat.com/oauth/authorize?
response_type=code&
client_id={CLIENT_ID}&
redirect_uri={REDIRECT_URI}


Token URL:     https://clientheartbeat.com/oauth/token


        

Responses

Client Heartbeat's JSON API uses HTTP response codes to indicate success, failure, and other errors.

1xx: Informational
2xx: Success
3xx: Redirection
4xx: Client Error
5xx: Server Error
        

Versioning

As we continue to update and improve the API, any changes that are incompatible with the current version will result in a new version. We may deprecate older versions as time goes on, but we'll let you know well in advance.

You specify the version in the URL, i.e. https://clientheartbeat.com/api/v{VERSION_NUMBER}.

Current version: 1.0
Current path:    https://clientheartbeat.com/api/v1
Release date:    2013/12/05




        

/users.json

List of users that belong to the current account.

### Request

GET /users

### Response

[
  {
    "id":         1,
    "account_id": 1,
    "email":      "[email protected]",
    "name":       "User One"
  },
  {
    "id":         2,
    "account_id": 1,
    "email":      "[email protected]",
    "name":       "User Two"
  },
  {
    "id":         3,
    "account_id": 1,
    "email":      "[email protected]",
    "name":       "User Three"
  }
]
        

/users/current.json

The currently logged in user.

### Request

GET /users/current

### Response

{
  "id":             1,
  "account_id":     1,
  "email":          "[email protected]",
  "name":           "User One",
  "receive_alerts": false
}
        

/accounts.json

List of accounts that the current user belongs to.

### Request

GET /accounts

### Response

[
  {
    "id":     1,
    "name":   "Example Company",
    "domain": "examplecompany.clientheartbeat.dev"
  }
]
        

/accounts/current.json

The current account.

### Request

GET /accounts/current

### Response

{
  "id":       1,
  "name":     "Example Company",
  "domain":   "examplecompany.clientheartbeat.dev",
  "code":     "AAAAaaaa",
  "color":    null,
  "logo":     null,
  "location": {
    "country": "AU",
    "state":   "QLD"
  }
}
        

/pulses.json

List of pulses that belong to the current account.

### Request

GET /pulses

### Response

[ 
  {
    "id":         1,
    "account_id": 1,
    "code":       "1a2B3c4D",
    "created_at": "2013-06-01T00:30:00Z",
    "closed_at":  "2013-07-01T00:30:00Z",
    "question_1": 9.0,
    "question_2": 4.0,
    "question_3": 5.5,
    "question_4": 6.6,
    "overall":    8.0
  },
  {
    "id":         2,
    "account_id": 1,
    "code":       "2b3C4d5E",
    "created_at": "2014-01-01T00:30:00Z",
    "closed_at":  null,
    "question_1": 0,
    "question_2": 0,
    "question_3": 0,
    "question_4": 0,
    "overall":    0
  }
]
        

/pulses/{PULSE_ID}.json

A specific pulse, specified by the pulse's ID in the URL.

  • pulse_idinteger the id of the specific pulse
### Request

GET /pulses/{PULSE_ID}

### Response

{
  "id":         1,
  "account_id": 2,
  "code":       "1a2B3c4D",
  "created_at": "2013-06-01T00:30:00Z",
  "closed_at":  "2013-07-01T00:30:00Z",

  "question_1": {
    "change": 0.0,
    "score":  9.0,
    "id":     1,
    "name":   "Promptness"
  },

  "question_2": {
    "change": 0.0,
    "score":  4.0,
    "id":     2,
    "name":   "Accuracy"
  },

  "question_3": {
    "change": 0.0,
    "score":  5.5,
    "id":     3,
    "name":   "Partnership"
  },

  "question_4": {
    "change": 0.0,
    "score":  6.6,
    "id":     4,
    "name":   "Helpfulness"
  },

  "overall": {
    "change": 8.0,
    "score":  0
  },

  "advocates": {
    "change": 0.0,
    "count":  4
  },

  "recommenders": {
    "change": 0.0,
    "count":  6
  },

  "detractors": {
    "change": 0.0,
    "count":  2
  },

  "heartbeats": {
    "received":  12,
    "opted_out": 2,
    "total":     15
  }
}
        

/contacts.json

An array of all contacts for the current account.

  • group_namestring filter contacts by their group name.
  • at_riskboolean filter all contacts by their risk status.
  • external_service_idstring filter contacts by their external service ID.
### Request

GET /contacts

GET /contacts?at_risk=true

### Response

[
  {
    "id":                 1,
    "first_name":         "User",
    "last_name":          "1",
    "email":              "[email protected]",
    "company":            "Company 1",
    "group_name":         "Group 1",
    "opted_out":          false,
    "at_risk":            null
  },
  {
    "id":                 2,
    "first_name":         "User",
    "last_name":          "2",
    "email":              "[email protected]",
    "company":            "Company 1",
    "group_name":         "Group 1",
    "opted_out":          false,
    "at_risk":            false
  },
  {
    "id":                 3,
    "first_name":         "User",
    "last_name":          "3",
    "email":              "[email protected]",
    "company":            "Company 2",
    "group_name":         "Group 2",
    "opted_out":          false,
    "at_risk":            true
  }
]
        

/contacts.json

Create a new contact.

  • first_namestring
  • last_namestring
  • emailstring
  • companystring
  • group_namestring
  • external_service_idstring
### Request

POST /contacts

{
  "first_name":           "User",
  "last_name":            "1",
  "email":                "[email protected]",
  "company":              "Company 1",
  "group_name":           "Group 1"
  "external_service_id":  "2001"
}

### Response

{
  "id":                   1,
  "current_heartbeat_id": 1,
  "external_service_id":  "2001",
  "first_name":           "User",
  "last_name":            "1",
  "email":                "[email protected]",
  "company":              "Company 1",
  "group_name":           "Group 1",
  "opted_out":            false,
  "at_risk":              null,
  "status":               "Waiting",
  "sentiment":            "",
  "created_at":           "2013-12-31T03:54:37Z",
  "last_sent_at":         "2013-12-31T03:54:55Z"
}
        

/contacts/{CONTACT_ID}.json

A specific contact, specified by the contact's ID in the URL.

  • contact_idinteger the id of the specific contact
### Request

GET /contacts/{CONTACT_ID}

### Response

{
  "id":                   1,
  "current_heartbeat_id": 1,
  "external_service_id":  "2001",
  "first_name":           "User",
  "last_name":            "1",
  "email":                "[email protected]",
  "company":              "Company 1",
  "group_name":           "Group 1",
  "opted_out":            false,
  "at_risk":              null,
  "status":               "Waiting",
  "sentiment":            "",
  "created_at":           "2013-12-31T03:54:37Z",
  "last_sent_at":         "2013-12-31T03:54:55Z"
}
        

/contacts/{CONTACT_ID}.json

A specific contact, specified by the contact's ID in the URL.

  • contact_idinteger the id of the specific contact
  • first_namestring
  • last_namestring
  • emailstring
  • companystring
  • group_namestring
  • external_service_idstring
### Request

PUT /contacts/{CONTACT_ID}

{
    "last_name": "One",
    "email":     "[email protected]"
}

### Response

{
  "id":                   1,
  "current_heartbeat_id": 1,
  "external_service_id":  "2001",
  "first_name":           "User",
  "last_name":            "One",
  "email":                "[email protected]",
  "company":              "Company 1",
  "group_name":           "Group 1",
  "opted_out":            false,
  "at_risk":              null,
  "status":               "Waiting",
  "sentiment":            "",
  "created_at":           "2013-12-31T03:54:37Z",
  "last_sent_at":         "2013-12-31T03:54:55Z"
}
        

/heartbeats.json

A summary of heartbeats from the last pulse for the account.

### Request

GET /heartbeats

### Response

[
  {
    "id":         1,
    "pulse_id":   1,
    "contact_id": 1,
    "score":      null
  },
  {
    "id":         2,
    "pulse_id":   1,
    "contact_id": 2,
    "score":      9
  },
  {
    "id":         3,
    "pulse_id":   1,
    "contact_id": 3,
    "score":      4
  }
]
        

/heartbeats/{PULSE_ID}.json

Details heartbeats for a specific pulse.

  • pulse_idinteger the id of the specific pulse
### Request

GET /heartbeats/{PULSE_ID}

### Response

[
  {
    "id":                 1,
    "pulse_id":           1,
    "contact_id":         1,
    "first_name":         "User",
    "last_name":          "1",
    "email":              "[email protected]",
    "company":            "Company 1",
    "group_name":         "Group 1",
    "overall":            null,
    "overall_change":     null,
    "answer_1":           null,
    "answer_1_change":    null,
    "answer_2":           null,
    "answer_2_change":    null,
    "answer_3":           null,
    "answer_3_change":    null,
    "answer_4":           null,
    "answer_4_change":    null,
    "testimonial":        null,
    "comment":            null,
    "status_code":        "waiting",
    "status_name":        "Waiting",
    "status_title":       "Customer is yet to respond to his/her Heartbeat",
    "date":               "2014-1-1T00:30:00Z",
    "code":               "1a2B3c4D"
  },
  {
    "id":                 2,
    "pulse_id":           1,
    "contact_id":         2,
    "first_name":         "User",
    "last_name":          "2",
    "email":              "[email protected]",
    "company":            "Company 1",
    "group_name":         "Group 1",
    "overall":            9,
    "overall_change":     null,
    "answer_1":           9,
    "answer_1_change":    null,
    "answer_2":           9,
    "answer_2_change":    null,
    "answer_3":           9,
    "answer_3_change":    null,
    "answer_4":           9,
    "answer_4_change":    null,
    "testimonial":        null,
    "comment":            "This is an example comment.",
    "status_code":        "ok",
    "status_name":        "Responded",
    "status_title":       "Has responded in your favour to their Heartbeat",
    "date":               "2014-1-1T00:30:00Z",
    "code":               "2b3C4d5E"
  },
  {
    "id":                 3,
    "pulse_id":           1,
    "contact_id":         3,
    "first_name":         "User",
    "last_name":          "3",
    "email":              "[email protected]",
    "company":            "Company 2",
    "group_name":         "Group 2",
    "overall":            4,
    "overall_change":     null,
    "answer_1":           5,
    "answer_1_change":    null,
    "answer_2":           7,
    "answer_2_change":    null,
    "answer_3":           7,
    "answer_3_change":    null,
    "answer_4":           4,
    "answer_4_change":    null,
    "testimonial":        null,
    "comment":            null,
    "status_code":        "risk",
    "status_name":        "At Risk",
    "status_title":       "Customer is likely to be unsatisfied with your services",
    "date":               "2014-1-1T00:30:00Z",
    "code":               "3c4D5e6F"
  }
]