Documentation

API Reference :: contacts

GET

Get contact information

• customerid - optional string - customerid of the subaccount you want to get a contact or contact list for.
• id - optional string - Contact id of the contact you want to get. If absent, the call will return a list of contacts. Getting a specific contact belonging to a subaccount requires customerid to be set.

Request example:

curl -X GET 'https://api.nodeping.com/api/1/contacts?'

Response example:

{
  "201205050153W2Q4C-BKPGH": {
    "_id": "201205050153W2Q4C-BKPGH",
    "type": "contact",
    "customer_id": "201205050153W2Q4C",
    "name": "Foo Bar",
    "custrole": "owner",
    "addresses": {
      "K5SP9CQP": {
        "address": "foo@example.com",
        "status": "new"
      }
    }
  }
}

---

POST and PUT

Create (POST) or update (PUT) a contact

• customerid - optional string - customerid of the subaccount to which the contact belongs. Not needed if the contact is in your primary account.
• id - required on update, ignored on create - string contact id you want to modify
• name - optional string - The name of the contact. It is used as a label.
• custrole - optional string - Set to 'edit,' 'view' or 'notify' to set permissions for this contact. Default is 'view'. Contacts created with an 'edit' or 'view' access level will receive a welcome email message, which by default includes a random password and the suggestion that they change the password immediately. You can avoid these messages by creating the contact with a 'notify' custrole, and then updating them to 'edit' or 'view'. You can also change the content of the welcome email message in the Branding preferences.
• addresses - optional JSON collection style object used to update existing email addresses and phone numbers. Not used for POST calls. When updating existing addresses, the entire list is required. Entries missing from the object are removed from the contact (there isn't a separate delete call for this purpose). Adding non-existing address IDs to the list will generate an error. Up, down, first, and diagnostic notifications can be suppressed for each address and you can mute each contact method. See the comments in newaddresses below for more information. The format is {addressid:{"address":emailaddress, "suppressfirst":true, "mute": 1633637541000},addressid2:{"address":phonenumber}}. See the example below.
• newaddresses - optional JSON array of objects used to add new email addresses and phone numbers to the contact. The format is: [{"address":emailaddress,"type":"email"},{"address":phonenumber,"type":"sms","mute":true}]. The type of address can be any supported address type, including "email", "sms", "webhook", "slack", "hipchat", "pushover", "pagerduty", or "voice". IDs will be automatically generated and assigned to each address entry as it is added to the contact. "Up", "Down", "First result", and "Diagnostic" alerts can be suppressed for each address by adding "suppressup":true, "suppressdown":true, "suppressfirst":true, and "suppressdiag":true to the address object. All notifications can be suppressed to an address by setting "suppressall": true. To remove any of these suppress settings, set it to false ("suppressfirst":false). To mute all notifications for a contact method, set "mute" to true. Set "mute" to a millisecond timestamp (UTC) in the future to mute all notifications to this contact method and have it automatically unmuted at that time. See the example below.

pushover - additional parameter for the pushover notification type:

• priority - optional integer - defaults to 2. Other valid values are 1, 0, -1, or -2 per the priority API documentation for Pushover.

webhooks - additional parameters for the webhook notification type:

• action - optional string - defaults to 'get' but can be 'put', 'post', 'head', or 'delete'
• data - optional string - payload or body of an HTTP POST or PUT request. This can be JSON, XML, or any arbitrary string.
• headers - optional object - set HTTP request headers like {"Content-Type": "application/json"}
• querystrings - optional object - set HTTP query string key/values like {"querykey1":"value1"}. These will be appended to your webhook URL as part of the query string.

Our webhooks provide basic templating as described in our webhook documentation.

Request example adding a new email address to an existing contact:

curl -X PUT -d'json={"newaddresses":[{"address":"sam@example.com","type":"email", "suppressup":true, "mute":false}]}' 'https://api.nodeping.com/api/1/contacts/201205050153W2Q4C-BKPGH'

Response example:

{
    "_id": "201205050153W2Q4C-BKPGH",
    "type": "contact",
    "customer_id": "201205050153W2Q4C",
    "name": "Foo Test",
    "custrole": "view",
    "sdomain": "nodeping.com",
    "addresses": {
        "K5SP9CQP": {
            "address": "foo@example.com",
            "type": "email"
        },
        "9ZODE0VF": {
            "address": "sam@example.com",
            "type": "email",
            "suppressup": true,
            "mute": false
        }
    }
}

---

DELETE

Delete a contact

• customerid - optional string - customerid of the subaccount to which the contact belongs. Not needed if the contact is in your primary account.
• id - required string - Contact id of the contact you want to delete.

Request example:

curl -X DELETE https://api.nodeping.com/api/1/contacts/201205050153W2Q4C-LZ1UI

Response example:

{"ok":true,"id":"201205050153W2Q4C-LZ1UI"}

---

RESETPASSWORD

Reset password for a contact. A new password will be emailed to the contact.

• customerid - optional string - customerid of the subaccount to which the contact belongs. Not needed if the contact is in your primary account.
• id - required string - Contact id of the contact for which you want to reset the password.

Request example:

curl -X GET https://api.nodeping.com/api/1/contacts/201205050153W2Q4C-OVDN7?action=RESETPASSWORD

Response example:

{"success":true}