« Back to Planio Blog
607c2ad02d6f256ecc9cfb8b02e8559a
Felix Schäfer
I am an engineer at Planio. I care for happy customers and an even better Planio.
November 19, 2013 · 2 min read

New API for Planio customer companies and contacts

I am pleased to announce that we have added a REST-style API for customer companies and customer contacts to Planio. Using this API, developers can programmatically list, read, create, update, and delete companies and contacts in Planio. This could for example be used to synchronize your customers from a third-party application with Planio.

The API works pretty much the same way as the rest of the Planio REST API, which as you might know is 100% compatible to Redmine's. As such, the General Topics of the Redmine REST API documentation apply to our new customer API as well. If you haven't read this document, I suggest you take a look at it. It explains how authentication is done, which formats can be used, etc.

This post covers the operations and options available for customer companies and contacts.

Customer companies

Listing companies

GET /companies.[format]

Returns a paginated list of companies. [format] can be either xml or json currently.

GET /projects/[project_identifier]/companies.[format]

Returns a paginated list of companies associated with the project with the identifier [project_identifier].

Available GET parameters:

Showing a company

GET /companies/[id].[format]

Returns the company with the ID id.

Creating a company

POST /companies.[format]

Creates a new company.

Available parameters (fields in document):

Example:

POST /companies.json
{
    "company": {
        "name": "Planio GmbH",
        "address1": "Lenbachstraße 7",
        "zip": "10245",
        "town": "Berlin",
        "state": "Berlin",
        "country": "Germany",
        "mails": [
            "support@plan.io",
            "kundenservice@plan.io"
        ],
        "phones": [
            {"kind": "work", "value": "+49 (30) 577 0000-0"},
            {"kind": "work_fax", "value": "+49 (30) 577 0000-99"}
        ],
        project_ids: ["1", "5"]
    }
}

Editing a company

PUT /companies/[id].[format]

Updates the company with the ID id. The available parameters for editing a company are the same as for company creation.

Deleting a company

DELETE /companies/[id].[format]

Deletes the company with the ID id.

Customer contacts

Listing contacts

GET /companies/[company_id]/contacts.[format]

Returns a list of the contacts associated with the company with the ID company_id.

Showing a contact

GET /companies/[company_id]/contacts/[id].[format]

Returns the contact with the ID id associated with the company with the ID company_id.

Creating a contact

POST /companies/[company_id]/contacts.[format]

Creates a new contact associated with the company with the ID company_id.

Available parameters (fields in document):

Example:

POST /companies/1/contacts.xml
<contact>
    <firstname>Felix</firstname>
    <lastname>Schäfer</lastname>
    <gender>true</gender>
    <mails type="array">
        <mail>support@plan.io</mail>
        <mail>kundenservice@plan.io</mail>
    </mails>
    <phones type="array">
        <phone kind="work" value="+49 (30) 577 0000-0"/>
        <phone kind="work_fax" value="+49 (30) 577 0000-99"/>
    </phones>
</contact>

Editing a contact

PUT /companies/[company_id]/contacts/[id].[format]

Updates the contact with the ID id associated with the company with the ID company_id. The parameters for editing a contact are the same as for contact creation.

Deleting a contact

DELETE /companies/[company_id]/contacts/[id].[format]

Deletes the contact with the ID id associated with the company with the ID company_id.

Have you used the Planio API before and/or are you planning to use the new customer API for your own projects and integrations? We would be thrilled to know. Please leave a comment below and tell us what you are building with Planio!

More articles about :