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
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 setDepartment
toSales
:
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 |
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 |
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
.