API Documentation

Introduction

The Atomic Contacts API is HTTP-based and attempts to conform to REST design principles. We strive to meet the same goals as Twitter's API:

  1. to be ridiculously simple
  2. to be obvious
  3. to be self-describing

Base URI

The base URI for version 1 of the API is: 

https://api.atomiccontacts.com/1/

The rest of this documentation specifies URLs as relative paths to this base. For example, 

GET contacts

means 

GET https://api.atomiccontacts.com/1/contacts

Please note that the protocol is HTTPS, not HTTP.

IDs

All resource IDs are 16-byte UUIDs in 32-character hexidecimal string format (i.e., no hyphens). 

fd0540d0109445e3a0601bc6e69f8f1d

Resource Formats

Requests should encode body data as form parameters and use the application/x-www-form-urlencoded content type.

Reponses will encode body data as JSON objects, or lists of objects, and use the application/json content type.

Pretty Printing

For ease of development, if you add a pretty=1 parameter to your request, we will format the response JSON and use the text/javascript, as opposed to application/json, content type.

Be sure to remove the pretty=1 parameter in your production code, though, since it slows things down a bit.

Character Encoding

UTF-8.

Dates and Times

UNIX epoch time.

While it's not the most expressive format, epoch time is relatively easy to use in most programming languages.

HTTP Method Override

Some HTTP clients only perform a subset of HTTP methods. To get around this limitation, a POST request can be made with the desired method specified using the method URL parameter. For example, if you were the following two requests are equivalent: 

DELETE /contacts/0123456789abcdef0123456789abcdef
POST /contacts/0123456789abcdef0123456789abcdef?method=delete

Authentication

HTTP Basic Authentication.

Response Objects

There are two types of response objects: User and Invite.

User

User objects are the primary API response type. An example user with all possible properties is below. Protected properties are only visible if the authenticating user is a contact of, or has received a request from, the user. Friendship fields describe the relationship between the authenticating user and the user. 

{
    // Guaranteed
    "id": "71c6d0c71f364233adc169f32d16fe0e", 
    "first_name": "Conrad", 
    "last_name": "Zunut", 
    "updated": 1278216000, 

    // Public
    "organization": "Malinker Inc.", 
    "title": "Quality Assurance Officer", 
    "home_locality": "New York", 
    "home_region": "NY", 
    "home_country": "USA", 
    "work_locality": "London", 
    "work_region": "England", 
    "work_country": "UK", 
	
    // Protected
    "home_email": "zuzu@example.com", 
    "home_mobile": "+1 (212) 555-2355", 
    "home_pin": "ABCD1234", 
    "home_phone": "+1 (212) 555-4663", 
    "home_phone_2": "+1 (212) 555-6262", 
    "home_street": "4 E 7th St.", 
    "home_street_2": "Apt. 09", 
    "home_postal_code": "10000", 
    "work_email": "conrad@example.com", 
    "work_mobile": "+44 20 7555 0001", 
    "work_pin": "4321DCBA", 
    "work_phone": "+44 20 7555 0002", 
    "work_street": "3 Threadneedle St.", 
    "work_street_2": "2nd Floor",
    "work_postal_code": "EC0A 0AA",

    // Relationship
    "mutual_contacts_count": 4, 
    "contact_added": 1246689325, 
    "request_sent": 1246766453, 
    "request_received": 1246852992, 
    "suggested": 1273584604, 
    "blocked": 1284575726,
	
    // Self
    "you": true
}

We do not bother returning null, false, 0 or empty string properties. If the above user had no contact information, contacts or relationship to the authenticating user, it would be rendered as follows. 

{
    "id": "71c6d0c71f364233adc169f32d16fe0e", 
    "first_name": "Conrad", 
    "last_name": "Zunut", 
    "updated": 1278216000 
}

The updated property indicates the last time the user updated his or her contact information.

Invite

Invite objects represent an unregistered email address to which the authenticating user has sent an invite. Invites are different from requests. In the Atomic Contacts system, a "request" is a relationship between two users, while an "invite" is a relationship between a user and an unregistered email address (i.e., non-user). When a user registers an email address, either by signing up or adding an additional account email address, any invites to that email become requests to that user. 

{
    "id": "ecedfbffa6524ba8a70044454520aae2",
    "email": "conrad@example.com",
    "sent": 1256449299
}

Errors

We return standard HTTP status codes for API request errors. The response body will also contain an error object, with an error property and, possibly, a detail properties. 

{
    "error": "missing_required_argument",
    "detail": "first_name"
}

The following list contains all API errors. The method definitions below list the errors raised by specific methods.

HTTP Status Error Property Detail Property
400 Bad Request invalid_date Invalid epoch date.
invalid_email Invalid email.
invalid_id Invalid ID.
missing_required_argument Missing argument name.
401 Unauthorized unauthorized None.
403 Forbidden block_exists Blocked user ID.
blocked Blocker user ID.
contact_exists Contact user ID.
email_registered Registered email.
invite_exists Invited email.
no_request_received Non-requester user ID.
request_received_exists Sender user ID.
request_sent_exists Recipient user ID.
suggestion_exists Suggested user ID.
user_exists Existing user ID.
why_me Authenticating user ID.
404 Not Found not_found User ID, email or none.

Resources

Resource HTTP Method Action
blocks GET Fetch Blocked Users
POST Block User
blocks/id DELETE Unblock User
contacts GET Fetch Contacts
POST Add Contact/Accept Request
contacts/id DELETE Delete Contact
GET Fetch Contact
contacts/batch POST Batch Add Contacts/Accept Requests
find GET Find Users
invites GET Fetch Invites
POST Send Invite
invites/id DELETE Cancel Invite
invites/batch POST Batch Send Invites
legal/privacy GET Fetch Privacy Policy
legal/terms GET Fetch Terms of Use
requests POST Request Contact
requests/batch POST Batch Request Contacts
requests/received GET Fetch Received Requests
requests/received/id DELETE Decline Received Request
requests/sent GET Fetch Sent Requests
requests/sent/id DELETE Cancel Sent Request
search GET Search Users
suggestions GET Fetch Suggestions
POST Trigger Suggestions
suggestions/id DELETE Hide Suggestion
sync POST Sync Changes
users POST Sign Up
you GET Fetch Self
PUT Update Self