Facten API v1 documentation


This documentation will show you how to interact with Facten programmatically using Facten's REST API version 1. All requests are validated against an API key (see section below).

Another option: built-in connectors (not documented here):

Looking for connect your Facten account to industry standards like Salesforce, Mailchimp, Marketo, Microsoft Dynamics etc.?

Built-in connectors already exist that can be used out-of-the-box. See more information here and contact us for details.

Yet another option: WebDAV (not documented here):

You can also interact with contacts and events in your Facten account through the CardDAV and CalDAV protocols. This can be achieved, either with existing compatible addressbook and calendar applications, or programmatically (for CardDAV, see RFC 6350, and this tutorial, for CalDAV, see RFC 5545, and this tutorial). The endpoint for both protocols is: https://www.facten.com/

URL scheme

The API uses a straightforward URL naming convention. Each request must be made to the API endpoint (https://www.facten.com/api/v1), followed by the type of object in singular form (e.g. https://www.facten.com/api/v1/contact). When one particular item is requested, the opaque identifier of the item must be appended to the URL (e.g. https://www.facten.com/api/v1/contact/contactId-123). In some cases a specific portion of the object can be requested by further appending to the identifier of the object (e.g. https://www.facten.com/api/v1/contact/contactId-123/events).

API key

All API requests are validated against an API key. The API key can be obtained manually by requesting a username and password from the Facten app. The API key is the concatenation of a username (6 lower-case letters or digits) followed by the dash "-" sign followed by the corresponding password (8 upper-case letters or digits). An API key could therefore look something like: w2ek5c-ATKH7G4L

A valid API key must be provided as part of the query string for all requests, using the api_key variable, e.g. https://www.facten.com/api/v1/contact/contactId-123?api_key=w2ek5c-ATKH7G4L


Any action you perform using this API (including from this page) will involve operations with your production data. Consider creating a separate Facten account for testing purposes.

All API traffic is encrypted using SSL/TLS. Do not place API calls over unencrypted HTTP as your data (and in particular your API key) might become visible to outsiders.

If you have any doubt on the secrecy of your API key, simply revoke it and create a new one from the Facten app.

This API is still being worked on. Minor details are subject to change.

Conventions, encoding and transport

All object identifiers are strings of the form typeId-xxxxxx. You should treat them as opaque objects.

Where applicable, objects are JSON-serialized, strings are UTF8-encoded, URLs are escaped. Dates and times follow ISO 8601 with explicit timezone information.

The API can handle CORS (Cross-Origin Resource Sharing) requests.

All API traffic is encrypted using SSL/TLS.

Push Notifications

You can subscribe to be notified in real time when particular actions occur in your Facten account. These notification will be in the form of HTTP POST requests to the URL of your choice. RequestBin is a convenient service to experiment.

As an example, if you subscribe to created.credential, you will receive a POST request like below whenever a user in your team creates a credential (either via Facten's web application or using this API).

    "data": {
        "credentialId": "credentialId-enkaxj",
        "label": "my iPhone"
    "date": "2015-02-25T22:00:02.712796+00:00",
    "event": "created.credential",
    "from": "facten-notification/1.0; (support@facten.com)",
    "id": "notificationId-5891733057437696-4817853794484224",
    "user": "userId-Lge4Gre0Ao"

See /admin/notification and contact support for details. The list of possible actions is:

To make live requests on your production data, you must either be signed in or place your API key here: