Contacts

The contact API allow to interact with the contact list stored on the Freebox

Contacts Errors

When attempting to access the contact API, you may encounter the following errors:

error_code Description
noent no entry with this id
exists an entry already exists
no_match no entry matched your request

Contact Objects

Contact Entry

Contact entries have the following properties

ContactEntry
id int

contact id

display_name string

contact display name

first_name string

contact first name

last_name string

contact last name

company string

contact company name

photo_url string

contact photo URL

NOTE the photo URL can be embedded (for instance “data:image/jpeg;base64,/9j/4AA [ ... ]”)

last_update timestamp

contact last modification timestamp

notes string

contact last modification timestamp

addresses[] array of ContactAddress

list of contact postal addresses

emails[] array of ContactEmail

list of contact email addresses

numbers[] array of ContactNumber

list of contact phone numbers

urls[] array of ContactUrl

list of contact URL

Contact Number

Contact number have the following properties

ContactNumber
id int

address id

contact_id int

id of the related contact

type enum

Type of number

Type Description
fixed fixed phone
mobile mobile phone
work work
fax fax
other other
number string
is_default bool

is this number the preferred contact phone number

is_own bool

is this number the Freebox owner number

Contact Address

Contact address have the following properties

ContactAddress
id int

address id

contact_id int

id of the related contact

type enum

Type of email

Type Description
home home address
work work address
other other
number string
street string
street2 string
city string
zipcode string
country string

Contact Url

Contact URL have the following properties

ContactUrl
id int

address id

contact_id int

id of the related contact

type enum

Type of URL

Type Description
profile profile address
blog blog address
site website address
other other
url string

URL address

Contact Email

Contact email have the following properties

ContactEmail
id int

address id

contact_id int

id of the related contact

type enum

Type of address

Type Description
home home address
work work address
other other
email string

email address

Contact API

Get a list of contacts

GET /api/v4/contact/

Returns the collection of all ContactEntry

Parameters:
  • start (int) – Offset
  • limit (int) – Limit of contact to return (-1 means no limit)
  • group_id (int) – Return only the contacts that belong to this group

Example request:

GET /api/v4/contact/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": [
        {
            "last_name": "Niel",
            "company": "Free",
            "photo_url": "data:image/jpeg;base64,/9j/4AA [ ... ]",
            "id": 2,
            "birthday": "",
            "last_update": 1363964483,
            "display_name": "",
            "emails": [
                {
                    "id": 2,
                    "contact_id": 2,
                    "type": "home",
                    "email": "rocket@launchpad.free"
                }
            ],
            "urls": [
                {
                    "id": 1,
                    "contact_id": 2,
                    "url": "http://www.free.fr/",
                    "type": "site"
                }
            ],
            "notes": "",
            "first_name": "Xavier"
        },

        [ ... ],

        {
            "last_name": "Mamie",
            "first_name": "Kipic",
            "company": "",
            "photo_url": "data:image/jpeg;base64,/9j/4A [ ... ] ",
            "id": 1,
            "birthday": "",
            "numbers": [
                {
                    "number": "0612345678",
                    "type": "fixed",
                    "id": 1,
                    "contact_id": 1,
                    "is_default": false,
                    "is_own": false
                }
            ],
            "last_update": 1363973599,
            "display_name": "Mamie",
            "emails": [
                {
                    "id": 1,
                    "contact_id": 1,
                    "type": "home",
                    "email": "mamie@example.org"
                }
            ],
            "urls": [
                {
                    "id": 3,
                    "contact_id": 1,
                    "url": "ftp://free.fr",
                    "type": "site"
                }
            ],
            "addresses": [
                {
                    "street2": "",
                    "type": "home",
                    "country": "France",
                    "id": 1,
                    "street": "8 rue du pont",
                    "contact_id": 1,
                    "city": "Paris",
                    "zipcode": "75008",
                    "number": "11"
                }
            ],
            "notes": ""
        }
}

Access a given contact entry

GET /api/v4/contact/{id}

Returns the ContactEntry with the given id

Example request:

GET /api/v4/contact/1 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
      "last_name": "Mamie",
      "first_name": "Kipic",
      "company": "",
      "photo_url": "data:image/jpeg;base64,/9j/4A [ ... ] ",
      "id": 1,
      "birthday": "",
      "numbers": [
          {
              "number": "0612345678",
              "type": "fixed",
              "id": 1,
              "contact_id": 1,
              "is_default": false,
              "is_own": false
          }
      ],
      "last_update": 1363973599,
      "display_name": "Mamie",
      "emails": [
          {
              "id": 1,
              "contact_id": 1,
              "type": "home",
              "email": "mamie@example.org"
          }
      ],
      "urls": [
          {
              "id": 3,
              "contact_id": 1,
              "url": "ftp://free.fr",
              "type": "site"
          }
      ],
      "addresses": [
          {
              "street2": "",
              "type": "home",
              "country": "France",
              "id": 1,
              "street": "8 rue du pont",
              "contact_id": 1,
              "city": "Paris",
              "zipcode": "75008",
              "number": "11"
          }
      ],
      "notes": ""
    }
}

Create a contact

POST /api/v4/contact/

Creates a new ContactEntry

Example request:

POST /api/v4/contact/ HTTP/1.1
Host: mafreebox.freebox.fr
{
   "display_name": "Sandy Kilo",
   "first_name": "Sandy",
   "last_name":"Kilo"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "last_name": "Kilo",
        "company": "",
        "photo_url": "",
        "id": 10,
        "birthday": "",
        "last_update": 1372433423,
        "display_name": "Sandy Kilo",
        "notes": "",
        "first_name": "Sandy"
    }
}

Delete a contact

DELETE /api/v4/contact/{id}

Deletes the ContactEntry with the given id.

Example request:

DELETE /api/v4/contact/1 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true
}

Update a contact entry

PUT /api/v4/contact/{id}

Updates the ContactEntry with the given id

Example request:

PUT /api/v4/contact/4 HTTP/1.1
Host: mafreebox.freebox.fr
{
  "company": "Freebox"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "last_name": "Anderson",
        "company": "Freebox",
        "photo_url": "data:image/jpeg;base64,/9j/4AAQ [ ... ]",
        "id": 4,
        "birthday": "",
        "last_update": 1363977825,
        "display_name": "Thomas A. Anderson",
        "emails": [
            {
                "id": 3,
                "contact_id": 4,
                "type": "home",
                "email": "neo@matrix.com"
            }
        ],
        "notes": "",
        "first_name": "Thomas"
    }
}