Redmine API at Planio

Planio is built on top of Redmine, an awesome open source project management software. Hence, the Planio API is 100% compatible to the Redmine REST API with a few additions and enhancements.

The Planio API is using REST (Representational state transfer) and provides the basic CRUD operations being Create, Read, Update, Delete via HTTPS.

As a representation format, the Redmine API (and hence Planio’s REST API) supports JSON and XML. In the following examples, we’ll sometimes use XML and sometimes JSON. However, all API operations support both formats.

Authentication

To get information about your user record using API authentication you could use this code:

curl 'https://example.plan.io/users/current.json' \
  -H 'X-Redmine-API-Key: 0123456789abcdef'

You would get JSON like this in return:

{
  "user": {
    "id": 123,
    "login": "john.doe@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "name": "John Doe",
    "mail": "john.doe@example.com",
    "created_on": "2007-10-06T13:47:36Z",
    "last_login_on": "2016-06-17T18:34:34Z",
    "api_key": "0123456789abcdef",
    "status": 1,
    "custom_fields": [{
      "id": 1,
      "name": "Work Phone",
      "value": "+1234567890"
    }]
  }
}

While some parts of the API can be used without authentication – depending on how you have configured your Planio account – most actions will require requests to be authenticated. In order for the REST API to work, please navigate to your avatar → Administration → Settings → Authentication and check the box next to Enable REST API.

With the REST API enabled in your Planio account, please navigate to your avatar → My account, open the sidebar and click on Show below the API Access Key header. After confirming your password, Planio will show your API key.

Now, to authenticate API requests, please add a custom HTTP header called X-Redmine-API-Key and supply your API key as a value.

User Impersonation

The following request would impersonate Jane Schmoe:

curl 'https://example.plan.io/users/current.json' \
  -H 'X-Redmine-API-Key: 0123456789abcdef' \
  -H 'X-Redmine-Switch-User: jane.schmoe@example.com'

As an administrator, you can use the API in order to submit requests assuming the identity of another user. In order to do that, please specify the user’s login as a value for the X-Redmine-Switch-User header.

Deprecated authentication methods

Please only use these authentication methods if using the X-Redmine-API-Key header is not possible.

For compatibility with the Redmine API, the Planio REST API also supports the following deprecated ways of authentication:

You can use your Planio/Redmine API key and supply it using either
- as the username part of HTTP Basic Authentication with a random or empty password, or
- as the value of a query string parameter called key (not recommended, because it may be stored as part of the URL in all sorts of log files).
You can use your regular Planio login (usually your email address) and your password and supply them using HTTP Basic Authentication.

Content type

To change the subject of issue #1 using JSON you could use this:

curl 'https://example.plan.io/issues/1.json' \
  -X PUT \
  -H 'X-Redmine-API-Key: 0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{ "issue": { "subject": "New subject" } }'

The same request using XML would look like this:

curl 'https://example.plan.io/issues/1.xml' \
  -X PUT \
  -H 'X-Redmine-API-Key: 0123456789abcdef' \
  -H 'Content-Type: application/xml' \
  -d '<issue><subject>New subject</subject></issue>'

When working with resources using the Redmine API at Planio, please specify the content type you are expecting to receive/send by using either the .json or .xml suffix in the URL.

When submitting content via POST or PUT, you will also have to specify the format by setting the Content-Type header.

When submitting JSON, please use Content-Type: application/json as a header.
When submitting XML, please use Content-Type: application/xml as a header.

Collections and Pagination

This will return the first 50 issues:

curl 'https://example.plan.io/projects.json?limit=50' \
  -H 'X-Redmine-API-Key: 0123456789abcdef'

To get 10 users starting at the 21st you’d use:

curl 'https://example.plan.io/users.xml?limit=10&offset=20' \
  -H 'X-Redmine-API-Key: 0123456789abcdef'

By default, when querying collection resources (e.g. /projects.json), you will only receive the first 25 objects in the collection.

To receive more objects you can use the following query parameters:

Parameter	Default	Description
limit	25	The number of objects to return in the response, maximum is 100
offset	0	The index of the first element to return

Associations

To get issue #123 including its history (i.e. journals) and repository commits (i.e. changesets):

curl 'https://example.plan.io/issues/123.xml?include=journals,changesets' \
  -H 'X-Redmine-API-Key: 0123456789abcdef'

Would return something like this:

<issue>

  <id>123</id>
  <subject>This is a bug</subject>
  <description>Please fix it</description>

  <!-- ... -->

  <changesets type="array">
    <changeset revision="42">
      <user id="9" name="John Doe"/>
      <comments>This fixes #123 @1h</comments>
      <committed_on>2016-01-09T09:50:31Z</committed_on>
    </changeset>
  </changesets>

  <journals type="array">
    <journal id="123">
      <user id="9" name="John Doe"/>
      <notes>Status applied in changeset r42.</notes>
      <created_on>2016-01-09T09:50:31Z</created_on>
      <details type="array">
        <detail property="attr" name="status_id">
          <old_value>1</old_value>
          <new_value>3</new_value>
        </detail>
      </details>
    </journal>
  </journals>

</issue>

To save requests, you can specify the associated objects you wish to receive included in your response using the include query parameter.

Parameter	Default	Description
include	—	A comma-separated list of associations to include

Custom fields

Fetching an issue will include its custom fields:

curl 'https://example.plan.io/issues/123.json' \
  -H 'X-Redmine-API-Key: 0123456789abcdef'

You would get JSON like this in return:

{
  "issue": {
    "id": 123,
    "subject": "A sample issue",
    "custom_fields": [{
      "id": 42,
      "name": "Department",
      "value": "Marketing"
    }]
  }
}

To update issue 123 and set Department to Sales:

curl 'https://example.plan.io/issues/123.json' \
  -X PUT \
  -H 'X-Redmine-API-Key: 0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d@- <<EOF
  {
    "issue": {
      "custom_fields" : [
        { "id": 42, "value": "Sales" }
      ]
    }
  }
EOF

The same request written in XML would look like this:

curl 'https://example.plan.io/issues/123.xml' \
  -X PUT \
  -H 'X-Redmine-API-Key: 0123456789abcdef' \
  -H 'Content-Type: application/xml' \
  -d@- <<EOF
  <issue>
    <custom_fields type="array">
      <custom_field id="42">
        <value>Sales</value>
      </custom_field>
    </custom_fields>
  </issue>
EOF

One of the strengths of Redmine (and thus Planio) is its customizability. You can define custom fields for most objects in Planio and set/get values via the user interface as well as via the REST API.

No additional URL parameters are required to get/set custom fields. The custom fields array will contain a number of custom field objects with the following attributes:

Attribute	Required	Description
id	yes	The internal id of this custom field
value	yes	The value of the custom field for this object, can be an array if `multiple` is set to `true`
name	no	The name of the custom field
multiple	no	Is `true` if the custom field allows multiple values to be set

To set custom fields in a POST or PUT request, be sure to include the custom field id with the request.

The custom field name is supplied when fetching objects via GET, but is’s not required when changing custom field values.

File attachments

Fetching an issue including all attachments:

curl 'https://example.plan.io/issues/123.xml?include=attachments' \
  -H 'X-Redmine-API-Key: 0123456789abcdef'

You would get XML like this in return:

<issue>
  <id>123</id>
  <subject>An issue with an attachment</subject>
  <description>This issue has a file attached to it.</description>
  <!-- ... -->
  <attachments type="array">
    <attachment>
      <id>41</id>
      <filename>example.png</filename>
      <filesize>13832</filesize>
      <content_type>image/png</content_type>
      <description>A sample image</description>
      <content_url>https://example.plan.io/attachments/download/41/example.png</content_url>
      <author id="123" name="John Doe"/>
      <created_on>2016-06-20T12:22:10Z</created_on>
    </attachment>
  </attachments>
</issue>

Some objects (e.g. issues, documents, wiki pages,…) support file attachments. They can be fetched like all other associations by setting the include=attachments query parameter. The attachments array will contain a number of attachment objects with the following attributes:

Attribute	Description
id	The internal id of this attachment
filename	The filename of this attachment
filesize	The size of this attachment in bytes
content_type	The content type of this attachment, e.g. `image/png`
description	The desription of this attachment
content_url	The URL at which the attachment can be downloaded
author	The user who has uploaded the attachment, identified by its `id` and `name`
created_on	The date and time at which the attachment was uploaded

Attaching files to new or existing objects is a two-step process:

Upload the file, receive a token
Create/Update the object, supply the token to attach the file

Uploading a file

To upload the local file example.png, issue a request like this:

curl 'https://example.plan.io/uploads.json' \
  -X POST \
  -H 'X-Redmine-API-Key: 0123456789abcdef' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @example.png

You will receive an id and a token like this:

{ "upload": { "id": 42, "token": "42.27774ef4d1a1bb92eb305e0b4526767c" } }

POST /uploads.[json|xml]

Simply issue a POST request to while setting the Content-Type header to application/octet-stream and include the file content in the request body.

The response will include the token for your uploaded file.

Attaching a file

To create a new issue and attach the previously uploaded image:

curl 'https://example.plan.io/projects/my-project/issues.json' \
  -X POST \
  -H 'X-Redmine-API-Key: 0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d@- <<EOF
  {
    "issue": {
      "subject": "A new issue with an image",
      "uploads" : [
        {
          "token": "42.27774ef4d1a1bb92eb305e0b4526767c",
          "filename": "example.png",
          "content_type": "image/png",
          "description": "A sample image"
        }
      ]
    }
  }
EOF

Now, you can create or update an object while supplying the token and file metadata as follows:

Attribute	Required	Description
token	yes	The token received in the previous step
filename	no	The filename for the file attachment
content_type	no	A content type which should be used to interpret the content, e.g. `image/png`
description	no	A short description to be displayed next to the filename

Validation and Errors

Creating a project without supplying a name like this:

curl 'https://example.plan.io/projects.json' \
  -X POST \
  -H 'X-Redmine-API-Key: 0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{ "project": { "description": "This is my project" }}'

Would yield a 422 Unprocessable Entity error response like this:

{
  "errors": [
    "Name can't be blank",
    "Identifier can't be blank"
  ]
}

Most objects in Planio apply constraints to the values being set for its attributes. If an object cannot be created or updated due to any of the constraints not being met, you will receive an HTTP response with status 422 Unprocessable Entity and a body detailing the problem.

Resources

This section provides detailed documentation on all resources available via the Redmine API at Planio.

Issues

A sample issue in XML format:

<issue>
    <id>123</id>
    <project id="1" name="Mission to Mars"/>
    <tracker id="2" name="Support"/>
    <status id="1" name="New"/>
    <priority id="4" name="Normal"/>
    <author id="5" name="John Doe"/>
    <category id="126" name="Maintenance"/>
    <fixed_version id="231" name="Takeoff"/>
    <subject>Rocket booster firmware upgrade</subject>
    <description>
      The current firmware for the rocket boosters
      needs to be updated.
    </description>
    <start_date/>
    <due_date/>
    <done_ratio>0</done_ratio>
    <is_private>false</is_private>
    <estimated_hours>30.0</estimated_hours>
    <spent_hours>0.0</spent_hours>
    <reply_token>abcdef</reply_token>
    <tracking_uri>
      https://example.plan.io/track/123/abcdef
    </tracking_uri>
    <created_on>2016-07-29T10:05:06Z</created_on>
    <updated_on>2016-07-29T10:05:11Z</updated_on>
    <closed_on/>
</issue>

Access issues in your Planio account via this endpoint.

Issue representations can have the following attributes:

Attribute	Required	Read-only	Description
id	no	yes	Internal identifier of this issue
project	yes	no	Project to which the issue belongs, identified by its `id` and `name`; see Projects
subject	yes	no	Issue subject
tracker	no	no	Tracker to which the issue belongs, identified by its `id` and `name`; see Trackers
status	no	no	Issue status, identified by its `id` and `name`; see Issue statuses
priority	no	no	Priority, identified by its `id` and `name`; see Issue priorities
author	no	yes	User who created the issue, identified by their `id` and `name`; see Users
category	no	no	Issue category, identified by its `id` and `name`; see Issue categories
fixed_version	no	no	Sprint/Milestone to which the issue belongs, identified by its `id` and `name`; see Sprints/Milestones
assigned_to_id	no	no	User to which the issue is assigned, identified by its `id` and `name`; see Users
parent	no	no	Issue of which this issue is a child issue, identified by its `id`
watchers	no	no	Array of users who are watching this issue, identified by their `id` and `name`; see Users
custom_fields	no	no	see custom fields
description	no	no	Issue description
start_date	no	no	Date on which the issue starts; formatted as `YYYY-MM-DD`
due_date	no	no	Date on which the issue is due; formatted as `YYYY-MM-DD`
done_ratio	no	no	% done percentage; an integer from `0-100`
is_private	no	no	Whether or not this issue is marked private; boolean
estimated_hours	no	no	Estimated time in hours; specify as float or `HH:MM`
spent_hours	no	yes	Total time tracked on this issue
reply_token	no	yes	A secret token required to update this issue via email when using Planio Help Desk
tracking_uri	no	yes	A secret URI which can be used to view those parts of the issue that are visible to the customer when using Planio Help Desk
created_on	no	yes	Date and time at which the issue was created; formatted as ISO 8601 timestamp
updated_on	no	yes	Date and time at which the issue was last updated; formatted as ISO 8601 timestamp
closed_on	no	yes	Date and time at which the issue was last set to a closed status; formatted as ISO 8601 timestamp

The attributes reply_token and tracking_uri are Planio additions which are not present in the standard Redmine API.

Listing issues

GET /issues.[json|xml]

A GET request will return a paginated list of issues.

Possible parameters:

Parameter	Default	Description
sort	—	Specify an attribute you’d like to sort by; append `:desc` for reverse the sort order
project_id	—	Filter by project; use a numeric id here
subproject_id	—	Filter by subproject; if you use `project_id=123&subproject_id=!*` you will receive only issues of project `123` and not issues of any of its subprojects
tracker_id	—	Filter by tracker; use a numeric id here
status_id	—	Filter by status; you can use `open`, `closed`, `*`, or a numeric status id here
assigned_to_id	—	Filter by assignee; use a numeric user id here, or `me` to get issues assigned to the authenticated user
created_on	—	Filter by date created; dates should be represented as ISO 8601; you can use additional operators `<=`, `>=` here
updated_on	—	Filter by date last updated; dates should be represented as ISO 8601; you can use additional operators `<=`, `>=` here
closed_on	—	Filter by date last closed; dates should be represented as ISO 8601; you can use additional operators `<=`, `>=` here
cf_$FIELD	—	Filter by custom field value; `$FIELD` must be a custom field id and the custom field must be defined as used as filter
include	—	Using `relations` as a value will return related issues as well
limit	25	The number of objects to return in the response, maximum is 100
offset	0	The index of the first element to return

Showing an issue

GET /issues/123.[json|xml]

A GET request will return a representation of a issue 123. The representation will be formatted as shown above.

The request can take a single parameter called include with one or more of these values, comma-separated:

Parameter	Description
children	Sub-issues that have the current issue as a parent
attachments	File attachments attached to the issue
relations	Issues related to this issue (duplicates, following, blocking, etc.)
changesets	Repository changesets associated with the issue
journals	History of changes made to this issue in the past
watchers	Users who are currently watching this issue

Creating an issue

POST /issues.[json|xml]

A POST request will create a new issue. The representation must be formatted as shown above. All parameters which are not marked as read-only can be set during a create request.

Associated objects have to be specified using the parameter name with an _id suffix, e.g. project_id.

Watchers can be set by supplying an array of user ids as a value for the watcher_user_ids parameter.

Issues (via contact forms)

Using Planio Help Desk, issues can be created in a simplified way, without authentication in third party web apps or via plain HTML web forms. To learn more, read the full guide on online forms with Planio.

Creating an issue via a web app

To create a new contact form issue:

curl 'https://example.plan.io/helpdesk.json' \
  -X POST \
  -H 'Content-Type: application/json' \
  -d@- <<EOF
  {
    "name": "Carl Customer",
    "mail": "carl.customer@example.com",
    "description": "How can I...?",
    "project": "support-project"
  }
EOF

POST /helpdesk.[json|xml]

The /helpdesk endpoint will accept unauthenticated requests using JSON or XML, so you can create contact form issues via your dynamic web site or third party application. It will create a new issue when Planio Help Desk is activated. Since the request will not need any authentication, it is perfect for contact forms.

Requests can include the following attributes:

Attribute	Required	Description
project	yes	Project in which the issue should be created, identified by its alpha-numric identifier; Planio Help Desk has to be enabled
mail	yes	Email address of the customer opening the issue; will be used to match or create company and contact
name	no	Name of the customer opening the issue
subject	no	Issue subject; optional if `description` is given
description	no	Issue description; optional if `subject` is given
custom_field_values[issue][$ID]	no	Value for an issue custom field; `$ID` has to be the numeric id of the custom field
custom_field_values[company][$ID]	no	Value for a company custom field; `$ID` has to be the numeric id of the custom field
custom_field_values[contact][$ID]	no	Value for a contact custom field; `$ID` has to be the numeric id of the custom field

The response would look like this:

Location: https://example.plan.io/track/1234/0123456789abcdef
{
  "issue": {
    "id": 1234,
    "reply_token": "0123456789abcdef",
    "tracking_uri": "https://example.plan.io/track/1234/0123456789abcdef"
  }
}

The response will include a reduced issue representation with the following attributes:

Attribute	Required	Read-only	Description
id	no	yes	Internal identifier of this issue
reply_token	no	yes	A secret token required to update this issue via email when using Planio Help Desk
tracking_uri	no	yes	A secret URI which can be used to view those parts of the issue that are visible to the customer when using Planio Help Desk

You could display the tracking_uri to the user so they can follow their request status or you could store it in your database to show it to the user at a later point in time.

The /helpdesk endpoint is also available as `/track` for historical reasons.

Creating an issue using an HTML form

The following HTML code could be embedded into any web site:

<!-- CSS to hide honeypot field -->
<style media="screen">#url { display:none; }</style>

<form action="https://example.plan.io/helpdesk" method="POST">

  <label for="name">Your name:</label>
  <input name="name" id="name" type="text" />

  <label for="mail">Your email address:</label>
  <input name="mail" id="mail" type="email" />

  <label for="customer-no">Your Customer Number:</label>
  <input name="custom_field_values[company][123]" id="customer-no" type="text" />

  <label for="subject">Subject:</label>
  <input name="subject" id="subject" type="text" />

  <label for="description">Your message:</label>
  <textarea name="description" id="description"></textarea>

  <input name="project" type="hidden" value="example-project" />
  <input name="url" id="url" type="text" />
  <input type="submit" value="Submit request" />

</form>

POST /helpdesk

If you do not want to implement any server-side code at all, Planio will also accept an unauthenticated POST request with application/x-www-form-urlencoded form data.

This can be used to implement a contact form on an external web site which will create issues in Planio for each request. The form can include the same attributes as shown above.

You can include an extra form field called url as a Honeypot Captcha against SPAM. If a value is given for this attribute, the issue will not be created. To make this strategy work, the field should be hidden using CSS or JavaScript.

The request will return a 301 response with a Location header set to the URL specified in the request’s Referer header, resulting in a redirect back to the originating URL.

Repositories

A sample repository in JSON format:

{
  "repository": {
    "id": 123,
    "project": { "id": 42, "name": "My project" },
    "identifier": "",
    "is_default": true,
    "scm": "git",
    "ssh_url": "git@example.plan.io:my-project.git",
    "branches": [
      { "name": "master" },
      { "name": "feature/acme-widgets" }
    ],
    "disksize": 62828372,
    "created_on": "2016-07-14T17:43:34Z"
  }
}

A sample repository in XML format:

<repository>
  <id>124</id>
  <project id="42" name="My project"/>
  <identifier>documents</identifier>
  <is_default>false</is_default>
  <scm>subversion</scm>
  <is_mirrored>false</is_mirrored>
  <svn_url>https://example.plan.io/svn/my-project.documents</svn_url>
  <disksize>2168821</disksize>
  <created_on>2016-04-16T11:28:59Z</created_on>
</repository>

Access the hosted Git and Subversion repositories within your Planio account via this endpoint.

Repository representations are composed as follows:

Attribute	Required	Read-only	Description
id	no	yes	Internal identifier of this repository
project	no	yes	Project to which the repository belongs, identified by its `id` and `name`
identifier	no	yes	Identifier of the repository; one repository per project can have an empty identifier
is_default	no	yes	Specifies whether the repository is the project’s default repository
scm	no	yes	Source control management system used for this repository, either `git` or `subversion`
ssh_url	no	yes	SSH clone URL to access the repository; only if `scm` is `git`
svn_url	no	yes	Subversion HTTPS URL to access the repository; only if `scm` is `subversion`
is_mirrored	no	yes	If this repository is mirrored from an external host; only if `scm` is `git`
mirror_from_url	no	yes	URL of the externally hosted repository from where this repository is mirrored; only if `is_mirrored` is `true`
branches	no	yes	Array of available branches for this repository
disksize	no	yes	The size of the repository in bytes
created_on	no	yes	Date and time at which the repository was created

The Repositories endpoint is a Planio addition and is not present in the standard Redmine API.

Listing repositories

This will return a list of repositories you have access to:

curl 'https://example.plan.io/repositories.json' \
  -H 'X-Redmine-API-Key: 0123456789abcdef'

GET /repositories.[json|xml]

A GET request will return a paginated list of repositories.

Possible parameters:

Parameter	Default	Description
include	—	Using `branches` as a value will return the list of branches
scm	—	Only list repositories of the specified SCM type; possible values are `git` or `subversion` or nothing at all
limit	25	The number of objects to return in the response, maximum is 100
offset	0	The index of the first element to return

Companies

A sample company in XML format:

<company>
  <id>12</id>
  <name>Planio GmbH</name>
  <address1>Rudolfstr. 14</address1>
  <address2/>
  <zip>10245</zip>
  <town>Berlin</town>
  <state/>
  <country>Germany</country>
  <country_code>de</country_code>
  <issue_priority id="5" name="High"/>
  <mails type="array">
    <mail>support@plan.io</mail>
  </mails>
  <phones type="array">
    <phone value="+49 (30) 577 0000-0" kind="work"/>
  </phones>
  <projects type="array">
    <project id="5" name="Support"/>
  </projects>
  <created_on>2016-12-19T11:13:34Z</created_on>
  <updated_on>2016-12-19T11:14:01Z</updated_on>
</company>

Company representations can have the following attributes:

Attribute	Required	Read-only	Description
id	no	yes	Internal identifier of this company
name	yes	no	Company name
address1	no	no	Address line 1
address2	no	no	Address line 2
zip	no	no	Postal code
town	no	no	City or town
state	no	no	State
country	no	yes	Full country name
country_code	no	no	ISO 3166-1 alpha-2 country code
issue_priority	no	no	Priority given to new issues created with this company identified by its `id` and `name`; see Issue priorities
mails	no	no	Array of emails associated with this company
phones	no	no	Array of phone numbers for this company identified by their `value` and `kind`
projects	no	no	Array of projects this company can be used in identified by their `id` and `name`; see Projects
custom_fields	no	no	see custom fields
created_on	no	yes	Date and time at which the company was created; formatted as ISO 8601 timestamp
updated_on	no	yes	Date and time at which the company was last updated; formatted as ISO 8601 timestamp

Listing companies

GET /companies.[json|xml]

A GET request will return a paginated list of companies.

Possible parameters:

Parameter	Default	Description
name	—	Filter by name, address, mails and phone of the company, first and last name, mails and phone of contacts, and searchable custom fields
project_id	—	Filter by project; use a numeric id here
limit	25	The number of objects to return in the response, maximum is 100
offset	0	The index of the first element to return

Showing a company

GET /companies/123.[json|xml]

A GET request will return a representation of company 123. The representation will be formatted as shown above.

Creating a company

POST /companies.[json|xml]

A POST request will create a new company. The representation must be formatted as shown above. All parameters which are not marked as read-only can be set during a create request.

Associated objects have to be specified using the parameter name with an _id or _ids suffix, i.e. issue_priority_id and project_ids.

Updating a company

PUT /companies/123.[json|xml]

A PUT request will update company 123. The representation must be formatted as shown above. All parameters which are not marked as read-only can be set during an update request. Omitted parameters will not be changed.

Associated objects have to be specified using the parameter name with an _id or _ids suffix, i.e. issue_priority_id and project_ids.

Deleting a company

DELETE /companies/123.[json|xml]

A DELETE request will delete company 123.

Contacts

A sample contact in XML format:

<contact>
  <id>15</id>
  <projects>
    <project id="5" name="Support" identifier="support"/>
  </projects>
  <company id="12" name="Planio GmbH"/>
  <firstname>Louise</firstname>
  <lastname>Engel</lastname>
  <gender>false</gender>
  <mails>
    <mail>support@plan.io</mail>
  </mails>
  <phones>
    <phone kind="work">+49 (30) 577 0000-0</phone>
  </phones>
  <created_on>2016-12-19 15:25:03 UTC</created_on>
  <updated_on>2016-12-19 15:25:35 UTC</updated_on>
</contact>

Contact representations can have the following attributes:

Attribute	Required	Read-only	Description
id	no	yes	Internal identifier of this contact
projects	no	yes	Array of projects this contact can be used in identified by their `id`, `name` and `identifier`; see Projects
company	yes	no	Company this contact is associated to identified by its `id` and `name`; see Companies
firstname	no	no	First name of the contact
lastname	no	no	Last name of the contact
gender	no	no	Gender of the contact, `true` is male, `false` is female, can be left blank
mails	no	no	Array of emails associated with this contact
phones	no	no	Array of phone numbers for this contact identified by their `value` and `kind`
custom_fields	no	no	see custom fields
created_on	no	yes	Date and time at which the contact was created; formatted as ISO 8601 timestamp
updated_on	no	yes	Date and time at which the contact was last updated; formatted as ISO 8601 timestamp

Listing contacts

GET /companies/123/contacts.[json|xml]

A GET request will return a paginated list of contacts associated with the company 123.

Showing a contact

GET /companies/123/contacts/456.[json|xml]

A GET request will return a representation of contact 456 of company 123. The representation will be formatted as shown above.

Creating a contact

POST /companies/123/contacts.[json|xml]

A POST request will create a new contact of company 123. The representation must be formatted as shown above. All parameters which are not marked as read-only can be set during a create request.

Updating a contact

PUT /companies/123/contacts/456.[json|xml]

A PUT request will update contact 456 of company 123. The representation must be formatted as shown above. All parameters which are not marked as read-only can be set during an update request. Omitted parameters will not be changed.

Deleting a contact

DELETE /companies/123/contacts/456.[json|xml]

A DELETE request will delete contact 456 of company 123.