An unofficial client for the Couple App API.

Usage no npm install needed!

<script type="module">
  import coupleApi from '';


npm version Build Status Coverage Status Dependency Status

Couple API

An unofficial Node client and command-line interface for the Couple App API.

An excellent web client is available for Couple, but it seems to be using a somewhat outdated version of Couple's internal API ("Juliet" Version: 1.40). For stability and access to the latest features, this library is built around the API methods used by the Couple iOS app ("Juliet" Version: 1.70).

WIP : Please note, methods marked "WIP" are not yet implemented.

This library is currently only intended for interaction with the Couple timeline, and does not include methods for interacting with Lists, Settings, or the Calendar. Please feel free to open an issue, if you'd like to see it expanded!

Node Client

Before interacting with the Couple API, you'll need to authenticate your client instance.


The authenticate method retrieves your Couple App authObject using your username and password.

The authObject contains both your user profile and the profile of your other. It also contains your authToken, which is needed to authenticate other API calls. The authToken seems to expire at least monthly, as well as when the user's password is changed.

var couple = new Couple();
var email = '';
var password = 'hunter2';
couple.authenticate(email, password, function(err, resObj) {
  if(err) return console.error(err);
  console.log('Client `couple` is authenticated:');

WIP: Timeline

All events – messages, stickers, nudges (Thinking of you...), etc. – are recorded in the Timeline. Upon logging in, the mobile apps begin downloading the timeline, 1600 events at a time, fetching and downloading media as it's encountered.

The Timeline function accepts an options object and a callback, and returns a Timeline object. The Timeline object includes all the information returned by the Couple API, as well as some convenience properties to make consecutive calls easier.

var options = {
  // using defaults:
  // limit: 1600,
  // order: desc,
  // after: ''

couple.timeline(options, function(err, timeline) {
  if(err) return console.error(err);


Note, the web app (API version 1.40) has a /moments endpoint (not currently implemented in this library), but the mobile apps rely on caching the timeline to generate the Moments section.

WIP: Sending

[Coming soon...]

Client API

var couple = require('couple-api');

All library methods are documented below. This library strives for 100% test coverage, so examples of all implemented functionality and sample Couple API responses can be found in the test directory.


couple.authenticate(email, password, callback);

Authenticates the couple-api instance. The method fetches the users AuthObject which contains a variety of information and is needed to authenticate all other calls.


Name Description
email The user's email address.
password The user's password.

callback(err, responseObject)

Called when the Couple API returns a response. All other methods can be called on the Couple instance after this callback is called. See tests for more detail.



Returns an identify object.

Name Description
userID The ID (email address) of the authenticated user.
authToken The user's base64 encoded authentication token.
otherID The ID (email address) of the other user paired with the authenticated user.
apiHost The full URL for Couple API server assigned to the user (to which requests are made).
userUuid A unique version 4 UUID assigned to the user by Couple.
pairUuid A unique version 4 UUID assigned to the pair by Couple.

WIP: Timeline

couple.timeline(options, callback);

Returns a segment of the authenticated user's Couple timeline.


Name Description
limit The number of events to return. It seems that Couple has not yet implemented a maximum limit, but it's probably best to rely on pagination in your app, rather than downloading the whole timeline at once. If not set, this property will use the default value used by the mobile apps, 1600.
order Chronological order of results. Options: desc or asc. Defaults to desc.
after Sets the starting point of the timeline segment retrieved. Accepts the itemID of the event occurring immediately before the first event in the response. By default, this is an empty string: '', causing the response to begin before the pair event, the first event in the whole timeline.

Callback(err, timeline)

Called when the Couple API returns a response.


The timeline object contains the events returned by the Couple API and additional properties.

// timeline:
  'firstItemID': 'timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx',
  'lastItemID': 'timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx',
  'events': [
      // event object
      // event object

Every entry in the Couple timeline is an event. The Couple timeline contains several types of events. All events have a number of similar properties.

Property Value
cver Couple app version which created the event. Prefix i for iOS (eg. i1.9.9), a for android, and w for the web client.
eventType The event type.
from The email of the user who created the event.
itemID A unique identifier – the event's timestamp, concatenated with a version 4 UUID. (timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx)
lID A unique 9 character, numerical ID – seems to be used internally by the mobile apps.
pairingID A unique version 4 UUID assigned to the pair by Couple.
timeStamp The timestamp of the event in milliseconds.

Each eventType also has a number of unique properties.


The text event is a normal message.

Property Value
eventType Set to text.
enc Text encoding. Only set on text events sent from the iOS app, which base64 encodes the text field. When set, the value is b64.
text The contents of the message. May be base64 encoded.
decodedText Property added to all text events by couple-api. Always contains the contents of the message.

The pair event is the first event in the timeline.

Property Value
eventType Set to pair.
pairType Seems to always be set to pair.

The pair event does not contain the cver, from, or lID properties.


The sticker event displays a sticker from a Couple sticker pack.

    "cver": "i1.9.9",
    "eventType": "sticker",
    "from": "",
    "itemID": "timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
    "lID": "#########",
    "pack": 19,
    "pairingID": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
    "sticker": 3,
    "timeStamp": 1430522000000
    "cver": "i1.9.9",
    "eventType": "nudge",
    "from": "",
    "itemID": "timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
    "lID": "#########",
    "pairingID": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
    "timeStamp": 1430522000000