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"
    }
}

Contact Related objects API

Contact related entries such as phone numbers, addresses, URLs and emails are all handled the same way.

Below we’ll document the numbers API, you can use the same calls with addresses, URL and emails.

Get the list of numbers for a given contact

GET /api/v4/contact/{contact_id}/[numbers|addresses|urls|emails]/

Returns the collection of all ContactNumber for a given contact

Example request:

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

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": [
        {
            "number": "+13374242",
            "type": "fixed",
            "id": 6,
            "contact_id": 4,
            "is_default": false,
            "is_own": false
        },
        {
            "number": "0611223344",
            "type": "mobile",
            "id": 5,
            "contact_id": 4,
            "is_default": false,
            "is_own": false
        }
    ]
}

Access a given contact number

GET /api/v4/[number,address,url,email]/{id}

Returns the ContactNumber with the given id

Example request:

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

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "number": "+13374242",
        "type": "fixed",
        "id": 6,
        "contact_id": 4,
        "is_default": false,
        "is_own": false
    }
}

Create a contact number

POST /api/v4/[number,address,url,email]/

Creates the ContactNumber

Example request:

POST /api/v4/number/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "contact_id":9,
   "number":"0144456789",
   "type":"fixed"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "number": "0144456789",
        "type": "fixed",
        "id": 18,
        "contact_id": 9,
        "is_default": false,
        "is_own": false
    }
}

Delete a contact number

DELETE /api/v4/[number,address,url,email]/{id}

Deletes the ContactNumber with the given id.

Example request:

DELETE /api/v4/number/6 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 number

PUT /api/v4/[number,address,url,email]/{id}

Updates the ContactNumber with the given id

Example request:

PUT /api/v4/number/5 HTTP/1.1
Host: mafreebox.freebox.fr

{
  "number": "0655667788",
  "type": "mobile"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "number": "0655667788",
        "type": "mobile",
        "id": 5,
        "contact_id": 4,
        "is_default": false,
        "is_own": false
    }
}