REST API v2

Preface
Errors
Global — Globally available actions (Global is no REST resource)
- GET /api2/mget — Fetch multiple items of any base type
- POST /api2/search — Search items
Account — Account represents the WebCRM account model
- Attributes
- GET /api2/accounts/:id — Fetch an account
- POST /api2/accounts — Create an account
- PUT /api2/accounts/:id — Update an account
- DELETE /api2/accounts/:id — Delete an account
- POST /api2/accounts/:id/merge_and_delete — Merge and delete an account
- GET /api2/accounts/:id/changes — Fetch the changelog of an account
Activity — Activity represents the WebCRM activity model
- Attributes
- GET /api2/activities/:id — Fetch an activity
- POST /api2/activities — Create an activity
- PUT /api2/activities/:id — Update an activity
- DELETE /api2/activities/:id — Delete an activity
- GET /api2/activities/:id/changes — Fetch the changelog of an activity
AttachmentStore — AttachmentStore represents actions related to activity attachments
- POST /api2/attachment_store/generate_upload_permission — Generate an upload permission to upload a file directly to S3
- POST /api2/attachment_store/generate_download_url — Generate a download URL
Collection — Collection represents the WebCRM collection model
- Attributes
- GET /api2/collections/:id — Fetch a collection
- POST /api2/collections — Create a collection
- PUT /api2/collections/:id — Update a collection
- DELETE /api2/collections/:id — Delete a collection
- PUT /api2/collections/:id/compute — Compute a collection
- GET /api2/collections/:id/output_ids — Get the computation result
- GET /api2/collections/:id/changes — Fetch the changelog of a collection
Contact — Contact represents the WebCRM contact model
- Attributes
- GET /api2/contacts/:id — Fetch a contact
- POST /api2/contacts — Create a contact
- PUT /api2/contacts/:id — Update a contact
- DELETE /api2/contacts/:id — Delete a contact
- POST /api2/contacts/:id/merge_and_delete — Merge and delete a contact
- GET /api2/contacts/:id/changes — Fetch the changelog of a contact
- PUT /api2/contacts/:id/clear_password — Clear the contact's password
- POST /api2/contacts/:id/generate_password_token — Generate a password token
- POST /api2/contacts/:id/send_password_token_email — Send an email containing a password token to the contact
- PUT /api2/contacts/:id/set_password — Set a new password
- PUT /api2/contacts/set_password_by_token — Set a new password by token
- PUT /api2/contacts/authenticate — Authenticate a contact by means of a login and a password
EventContact — EventContact represents the WebCRM event participation model
- Attributes
- GET /api2/event_contacts/:id — Fetch an event contact
- POST /api2/event_contacts — Create an event_contact
- PUT /api2/event_contacts/:id — Update an event contact
- DELETE /api2/event_contacts/:id — Delete an event contact
- GET /api2/event_contacts/:id/changes — Fetch the changelog of an event contact
Event — Event represents the WebCRM event model
- Attributes
- GET /api2/events/:id — Fetch an event
- POST /api2/events — Create an event
- PUT /api2/events/:id — Update an event
- DELETE /api2/events/:id — Delete an event
- GET /api2/events/:id/changes — Fetch the changelog of an event
Mailing — Mailing represents the WebCRM mailing model
- Attributes
- GET /api2/mailings/:id — Fetch a mailing
- POST /api2/mailings/:id/clone — Clone a mailing
- POST /api2/mailings — Create a mailing
- PUT /api2/mailings/:id — Update a mailing
- DELETE /api2/mailings/:id — Delete a mailing
- GET /api2/mailings/:id/changes — Fetch the changelog of a mailing
- POST /api2/mailings/:id/render_preview — Render a mailing preview
- POST /api2/mailings/:id/send_single_email — Send a single email
- POST /api2/mailings/:id/send_me_a_proof_email — Send a proof email
- POST /api2/mailings/:id/release — Release mailing
MailingDelivery — MailingDelivery represents a mailing delivery
- Attributes
- GET /api2/mailings/:mailing_id/mailing_deliveries — Fetch all mailing deliveries of a mailing
- GET /api2/mailings/:mailing_id/mailing_deliveries/:id — Fetch a mailing delivery
- PUT /api2/mailings/:mailing_id/mailing_deliveries/:id — Create or update a mailing delivery
- DELETE /api2/mailings/:mailing_id/mailing_deliveries/:id — Delete a mailing delivery
MailingRecipient — MailingRecipient represents a mailing recipient email address
- Attributes
- GET /api2/mailing_recipients — Fetch all mailing recipient email addresses
- GET /api2/mailing_recipients/:id — Fetch a mailing recipient email address
- PUT /api2/mailing_recipients/:id — Updating or creating a mailing recipient email address
TemplateSet — TemplateSet represents the singleton WebCRM template set
- Attributes
- GET /api2/template_set — Fetch the template set
- PUT /api2/template_set — Update the template set
- GET /api2/template_set/changes — Fetch the changelog of the template set
- POST /api2/template_set/render_preview — Render a preview of the template set
Type — Type represents the WebCRM type model
- Attributes
- GET /api2/types — Fetch all types
- GET /api2/types/:id — Fetch a type
- POST /api2/types — Create a type
- PUT /api2/types/:id — Update a type
- DELETE /api2/types/:id — Delete a type
- GET /api2/types/:id/changes — Fetch the changelog of a type

Preface

General Rules / Guidelines

On every change of a type, a global type version counter is incremented. The value of this counter is included in every HTTP response the API returns. A client may utilize the counter to update its type cache. The response header is "X-Types-Version".

PUT complains about keys that are not defined in the corresponding type of the item.

PUT does not complain about setting internal r/o keys. Clients can PUT the same data they received on GET w/o having to delete specific keys from the PUT request.

Timestamps are generally formatted in the ISO 8601 format, e.g. 2013-09-08T07:22:41Z or 2013-09-08T07:22:41+00:00. The timezone is always UTC.

Please note that new attributes/endpoints/actions/functionality can be introduced any time by Infopark. Clients should not expect responses to always contain the same set of keys. Nevertheless, newly added attributes will have default values and may be omitted in requests.

Request and response bodies are encoded in JSON.

Development with curl

Example:

curl -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u $CRM_USER:$CRM_API_KEY \ -XGET \ https://$CRM_TENANT.crm.infopark.net/api2/accounts/$ID

Errors

unauthorized

Authentication attempt with invalid API credentials

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`

HTTP Response Code: 401

Example:

{ "id": "unauthorized", "message": "Please validate credentials and try again." }

forbidden

The API User is not permitted to access the resource

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`

HTTP Response Code: 403

Example:

{ "id": "forbidden", "message": "The provided credentials do not provide access to the specified resource." }

not_found

The requested resource/resources cannot be found

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`
`missing_ids`	A list of IDs that could not be found	`array`

HTTP Response Code: 404

Example:

{ "id": "not_found", "message": "Items could not be found.", "missing_ids": ["9762b2b4382f6bf34adbdeb21ce588aa"] }

conflict

Someone else changed the item

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`

HTTP Response Code: 412

Example:

{ "id": "conflict", "message": "The item was changed by someone else." }

too_many_params

A POST or PUT of an item sets more than 1000 keys. This is either a DOS attack or the type is misconfigured.

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`

HTTP Response Code: 422

Example:

{ "id": "too_many_params", "message": "The request contains too many parameters." }

authentication_failed

Authentication of a contact failed

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`

HTTP Response Code: 422

Example:

{ "id": "authentication_failed", "message": "The provided credentials are wrong.", }

sending_email_failed

Sending an email failed

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`
`debug_info`	The root cause message	`string`

HTTP Response Code: 422

Example:

{ "id": "sending_email_failed", "message": "The email could not be sent.", "debug_info": "root cause message" }

invalid_values

The keys are all recognized but their values are partially incorrect. The code in a validation_errors field is one of Rails' validation error code symbols, e.g. :blank, :inclusion. An English message is provided for convenience, clients can provide a translation based on the code symbol.

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`
`validation_errors`	A list of model validation errors. The items in the list are hashes including a code (i.e. one of the Rails validation error codes), the attribute that has an invalid value, and an English message that is provided for convenience.	`array`

HTTP Response Code: 422

Example:

{ "id": "invalid_values", "message": "Validate the parameters and try again.", "validation_errors": [ { "code": "blank", "attribute": "name", "message": "name is blank" } ] }

invalid_keys

Attempt to set undefined keys. In contrast to the invalid_values error, this error is not based on validations in the model. Instead, setting invalid keys is already blocked on the API layer. If this error occurs, the validations defined in the model will not run at all. Internal r/o attributes are silently ignored.

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`
`validation_errors`	A list of model validation errors. The items in the list are hashes including a code (i.e. one of the Rails validation error codes), the attribute that has an invalid value, and an English message that is provided for convenience.	`array`

HTTP Response Code: 422

Example:

{ "id": "invalid_keys", "message": "Unknown keys specified.", "validation_errors": [ { "attribute": "foo", "code": "unknown", "message": "foo is unknown" } ] }

item_state_precondition_failed

One or more preconditions of the attempted action were not satisfied.

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`
`unmet_preconditions`	A list of unmet preconditions. The items in the list are hashes including a code (the symbolic name of the precondition), and an English message that is provided for convenience.	`array`

HTTP Response Code: 422

Example:

params_parse_error

The JSON parameters could not be parsed

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`
`debug_info`	The root cause message	`string`

HTTP Response Code: 422

Example:

{ "id": "params_parse_error", "message": "The sent params could not be parsed." "debug_info": "795: unexpected token at 'account'" }

rate_limit

The rate limit was exceeded

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`

HTTP Response Code: 429

Example:

{ "id": "rate_limit", "message": "Your account reached the API rate limit. Please wait a few minutes before making new requests." }

internal_server_error

An internal server error occurred

Response

Attributes:

Name	Description	Type
`id`	An ID describing the error	`string`
`message`	A short description of the error in English	`string`

HTTP Response Code: 500

Example:

{ "id": "internal_server_error", "message": "We have been notified about this issue, and we will take a look at it shortly." }

Global

Globally available actions (Global is no REST resource)

GET /api2/mget — Fetch multiple items of any base type

Use case: First search for items (may result in a large result set). Check your local app cache if it already contains some or all of the items in detail. Fetch missing items via mget. Iterate over the search result to fetch items in smaller batches. Note that mget has a much smaller limit than search because the amount of item data is supposed to be larger than the few keys returned by search.

Request

Required Parameters:

Name Description

Name	Description
`ids`	A list of IDs to fetch. Limit 100. Type: `array` Example: `[ "9762b2b4382f6bf34adbdeb21ce588aa", "4c562cc22b2dd164f353756526664589" ]`

ids

A list of IDs to fetch. Limit 100.

Type: array

Example:

[ "9762b2b4382f6bf34adbdeb21ce588aa", "4c562cc22b2dd164f353756526664589" ]

Requirements:

All requested IDs must exist

Response

A list of items, one for each requested ID. An empty array if no IDs were specified.

HTTP Response Code: 200

Example:

[ { "id": "9762b2b4382f6bf34adbdeb21ce588aa", "base_type": "Account", "type_id": "account", "version": 17, "name": "Firma XYZ", "locality": "Hamburg", […] }, { "id": "4c562cc22b2dd164f353756526664589", "base_type": "Contact", "type_id": "contact", "version": 1, "name": "Herr Meier", "locality": "Frankfurt", "gender": "M", […] } ]

POST /api2/search — Search items

Performs a search over the following base types: Account, Activity, Collection, Contact, Event, EventContact, Mailing.

Request

Optional Parameters:

Name	Description
`filters`	Array of filter clauses. Each clause is an object with three properties: `field`, `condition`, `value`. Clauses are AND expressions. A string value may contain "," to OR the parts. Returns all (taking account of limit) if no filter is specified. Filters do not affect score. Supported fields: `account_group`, `account_id`, `account_ids`, `account_name`, `base_type`, `changed_at`, `collection_type`, `contact_id`, `contact_ids`, `contact_name`, `country`, `created_at`, `created_by`, `dtend_at`, `dtstart_at`, `email`, `event_id`, `event_set`, `event_title`, `extended_address`, `fax`, `first_name`, `gender`, `geo_location`, `home_page`, `id`, `job_title`, `language`, `last_name`, `locality`, `location`, `login`, `mailing_id`, `mobile_phone`, `name`, `name_prefix`, `notes`, `org_name_address`, `org_unit_address`, `password_present`, `password_updated_at`, `phone`, `planned_release_at`, `postalcode`, `region`, `released_at`, `state`, `street_address`, `tags`, `title`, `type_id`, `updated_at`, `updated_by`, `want_phonecall`, `want_snailmail` Supported conditions: `contains_word_prefixes`, `contains_words`, `equals`, `is_blank`, `is_earlier_than`, `is_later_than`, `is_true`, `not_contains_word_prefixes`, `not_contains_words`, `not_equals`, `not_is_blank`, `not_is_earlier_than`, `not_is_later_than`, `not_is_true` Type: `array` Example: `[ { "field": "first_name", "condition": "contains_word_prefixes", "value": "Jo" }, { "field": "last_name", "condition": "not_is_blank" }, { "field": "gender", "condition": "equals", "value": ["M", "F"] } ]`
`query`	The search term of a full-text search for words starting with the term (case-insensitive prefix search). Affects score. Type: `string`
`limit`	The number of results to return at most. Min: 0. Max: 100. Type: `integer` Default: `10`
`offset`	The number of results to skip. Min: 0. Type: `integer` Default: `0`
`sort_by`	The attribute name by which to sort the result. Possible choices: `base_type`, `created_at`, `dtstart_at`, `first_name`, `last_name`, `score`, `title`, `updated_at` To achieve deterministic results, a second criterion (e.g. `id`) is added internally. Sorting by score is only useful if a query is given. Type: `string` Default: `score`
`sort_order`	One of `asc`, `desc`. For `score`, the only valid sort order is `desc` (can be omitted). Type: `string` Default: `asc`

Response

The search results

Parameters:

Name Description

Name	Description
`results`	A list of search hits. Each hit has the field `id`. Type: `array`
`total`	The number of hits regardless of limit Type: `integer`

results

A list of search hits. Each hit has the field id.

Type: array

total

The number of hits regardless of limit

Type: integer

HTTP Response Code: 200

Example:

{ "results": [ { "id": "9762b2b4382f6bf34adbdeb21ce588aa" }, { "id": "4c562cc22b2dd164f353756526664589" } ], "total": 2157 }

Account

Account represents the WebCRM account model

Attributes of Account

Name	Description
`base_type`	base_type is always Account. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Available for: `GET`, `POST`, `PUT` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always account. Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`account_group`	The name of the company group the account belongs to Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"Big Company"`
`country`	The name of the country in which the account is based (stored in uppercase). Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"GERMANY"`
`extended_address`	An address extension Type: `string` Available for: `GET`, `POST`, `PUT`
`home_page`	The company's website address (URL) Type: `string` Available for: `GET`, `POST`, `PUT`
`locality`	The city in which the account is based Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"Berlin"`
`merged_into_id`	Type: `string` Available for: `GET`
`name`	The name of the account Type: `string` Available for: `GET`, `POST`, `PUT`
`org_name_address`	Type: `string` Available for: `GET`, `POST`, `PUT`
`org_unit_address`	Type: `string` Available for: `GET`, `POST`, `PUT`
`phone`	The main phone number of the account Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"+49 30 123456789"`
`postalcode`	The postal code of the account Type: `string` Available for: `GET`, `POST`, `PUT`
`region`	The region in which the account is based Type: `string` Available for: `GET`, `POST`, `PUT`
`street_address`	The street name and building number of the account location Type: `string` Available for: `GET`, `POST`, `PUT`
`tags`	A list of tags Type: `array` Available for: `GET`, `POST`, `PUT` Example: `["abc", "def"]`
`want_geo_location`	Whether to lookup the geo coordinates for the address Type: `boolean` Available for: `GET`, `POST`, `PUT`

GET /api2/accounts/:id — Fetch an account

Response

The representation of the requested account

Parameters:

Name	Description
`base_type`	base_type is always Account. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always account. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_group`	The name of the company group the account belongs to Type: `string` Example: `"Big Company"`
`country`	The name of the country in which the account is based (stored in uppercase). Type: `string` Example: `"GERMANY"`
`extended_address`	An address extension Type: `string`
`home_page`	The company's website address (URL) Type: `string`
`locality`	The city in which the account is based Type: `string` Example: `"Berlin"`
`merged_into_id`	Type: `string`
`name`	The name of the account Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`phone`	The main phone number of the account Type: `string` Example: `"+49 30 123456789"`
`postalcode`	The postal code of the account Type: `string`
`region`	The region in which the account is based Type: `string`
`street_address`	The street name and building number of the account location Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`want_geo_location`	Whether to lookup the geo coordinates for the address Type: `boolean`

HTTP Response Code: 200

POST /api2/accounts — Create an account

Request

Required Parameters:

Name Description

Name	Description
`name`	The name of the account Type: `string`

name

The name of the account

Type: string

Optional Parameters:

Name	Description
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`account_group`	The name of the company group the account belongs to Type: `string` Example: `"Big Company"`
`country`	The name of the country in which the account is based (stored in uppercase). Type: `string` Example: `"GERMANY"`
`extended_address`	An address extension Type: `string`
`home_page`	The company's website address (URL) Type: `string`
`locality`	The city in which the account is based Type: `string` Example: `"Berlin"`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`phone`	The main phone number of the account Type: `string` Example: `"+49 30 123456789"`
`postalcode`	The postal code of the account Type: `string`
`region`	The region in which the account is based Type: `string`
`street_address`	The street name and building number of the account location Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`want_geo_location`	Whether to lookup the geo coordinates for the address Type: `boolean`

Response

The representation of the created account

Parameters:

Name	Description
`base_type`	base_type is always Account. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always account. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_group`	The name of the company group the account belongs to Type: `string` Example: `"Big Company"`
`country`	The name of the country in which the account is based (stored in uppercase). Type: `string` Example: `"GERMANY"`
`extended_address`	An address extension Type: `string`
`home_page`	The company's website address (URL) Type: `string`
`locality`	The city in which the account is based Type: `string` Example: `"Berlin"`
`merged_into_id`	Type: `string`
`name`	The name of the account Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`phone`	The main phone number of the account Type: `string` Example: `"+49 30 123456789"`
`postalcode`	The postal code of the account Type: `string`
`region`	The region in which the account is based Type: `string`
`street_address`	The street name and building number of the account location Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`want_geo_location`	Whether to lookup the geo coordinates for the address Type: `boolean`

HTTP Response Code: 201

PUT /api2/accounts/:id — Update an account

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name	Description
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`account_group`	The name of the company group the account belongs to Type: `string` Example: `"Big Company"`
`country`	The name of the country in which the account is based (stored in uppercase). Type: `string` Example: `"GERMANY"`
`extended_address`	An address extension Type: `string`
`home_page`	The company's website address (URL) Type: `string`
`locality`	The city in which the account is based Type: `string` Example: `"Berlin"`
`name`	The name of the account Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`phone`	The main phone number of the account Type: `string` Example: `"+49 30 123456789"`
`postalcode`	The postal code of the account Type: `string`
`region`	The region in which the account is based Type: `string`
`street_address`	The street name and building number of the account location Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`want_geo_location`	Whether to lookup the geo coordinates for the address Type: `boolean`

Response

The representation of the updated account

Parameters:

Name	Description
`base_type`	base_type is always Account. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always account. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_group`	The name of the company group the account belongs to Type: `string` Example: `"Big Company"`
`country`	The name of the country in which the account is based (stored in uppercase). Type: `string` Example: `"GERMANY"`
`extended_address`	An address extension Type: `string`
`home_page`	The company's website address (URL) Type: `string`
`locality`	The city in which the account is based Type: `string` Example: `"Berlin"`
`merged_into_id`	Type: `string`
`name`	The name of the account Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`phone`	The main phone number of the account Type: `string` Example: `"+49 30 123456789"`
`postalcode`	The postal code of the account Type: `string`
`region`	The region in which the account is based Type: `string`
`street_address`	The street name and building number of the account location Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`want_geo_location`	Whether to lookup the geo coordinates for the address Type: `boolean`

HTTP Response Code: 200

DELETE /api2/accounts/:id — Delete an account

For optimistic locking, send the current version in an If-Match HTTP header.

Response

HTTP Response Code: 200

POST /api2/accounts/:id/merge_and_delete — Merge and delete an account

Assigns the dependent docs/items of the account with ID id to merge_into_id after deleting id.

Request

Required Parameters:

Name Description

Name	Description
`merge_into_id`	The ID of the account to assign the dependent docs/items to Type: `string` Example: `"caba97c7f07801d57c148f977df26d62"`

merge_into_id

The ID of the account to assign the dependent docs/items to

Type: string

Example:

"caba97c7f07801d57c148f977df26d62"

Requirements:

merge_into_id != id

Response

HTTP Response Code: 200

GET /api2/accounts/:id/changes — Fetch the changelog of an account

Request

Optional Parameters:

Name Description

Name	Description
`limit`	The number of changelog entries to fetch at most. The max. limit is 100. Type: `integer` Default: `10`

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The account changelog

Parameters:

Name Description

Name	Description
`results`	The changelog entries in reverse order (newer -> older) Type: `array` Example: `[ { "changed_at": "2014-01-01T00:00:00Z", "changed_by": "root", "details": { "locality": { "before": "München", "after": "Berlin" }, "tags": { "before": ["foo", "bar"], "after": ["another", "tag"] } } }, { ... } ]`

results

The changelog entries in reverse order (newer -> older)

Type: array

Example:

[ { "changed_at": "2014-01-01T00:00:00Z", "changed_by": "root", "details": { "locality": { "before": "München", "after": "Berlin" }, "tags": { "before": ["foo", "bar"], "after": ["another", "tag"] } } }, { ... } ]

HTTP Response Code: 200

Activity

Activity represents the WebCRM activity model

Attributes of Activity

Name	Description
`base_type`	base_type is always Activity. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Available for: `GET`, `POST`, `PUT` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type ID of the item Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`account_ids`	The list of the accounts associated with the activity Type: `array` Available for: `GET`, `POST`, `PUT` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`dtend_at`	The ending time of an appointment. The activity is shown as a calendar entry. Must only be present if `dtstart_at` or `location` are set. Type: `datetime` Available for: `GET`, `POST`, `PUT`
`dtstart_at`	The starting time of an appointment. The activity will be shown as a calendar entry. Must only be present if `dtend_at` or `location` are set. Type: `datetime` Available for: `GET`, `POST`, `PUT`
`location`	The location of the appointment Type: `string` Available for: `GET`, `POST`, `PUT`
`contact_ids`	The list of the contacts associated with the activity Type: `array` Available for: `GET`, `POST`, `PUT` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`email_cc`	Additional email addresses (comma-separated). To have them receive notifications, add this field to the `notification_email_to` template. Type: `string` Available for: `GET`, `POST`, `PUT`
`state`	Activity state (one of the states of its type) Type: `string` Available for: `GET`, `POST`, `PUT`
`tags`	The list of the tags associated with the activity Type: `array` Available for: `GET`, `POST`, `PUT`
`title`	The activity title Type: `string` Available for: `GET`, `POST`, `PUT`
`comments`	The list of comments. An activity can have any number of comments. Comments are represented inline in the activity resource. They are append-only. Use the attributes `comment_notes`, `comment_attachments` etc. to append a new comment to the activity. It is not possible to edit or delete existing comments. Adding a comment updates `updated_at` and `version` in the activity. A comment has the following fields: `contact_id`: The comment author's ID. `notes`: The comment text. `attachments`: The comment attachments. The array of `strings` contains attachment IDs. `published`: Publicly visible? `boolean` `updated_at`: Comment date (`datetime`) `updated_by`: Login of the comment author Type: `array` Available for: `GET`
`comment_attachments`	New comment attachment IDs Type: `array` Available for: `POST`, `PUT`
`comment_contact_id`	When adding a comment, the ID of the contact person concerned can be specified using this field (can be set only). Type: `string` Available for: `POST`, `PUT`
`comment_notes`	New comment text Type: `string` Available for: `POST`, `PUT`
`comment_published`	The new comment is visible to the `contact_id` person of the activity and is sent to the email recipients. Type: `boolean` Available for: `POST`, `PUT`

GET /api2/activities/:id — Fetch an activity

Response

The representation of the requested account

Parameters:

Name	Description
`base_type`	base_type is always Activity. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type ID of the item Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_ids`	The list of the accounts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`dtend_at`	The ending time of an appointment. The activity is shown as a calendar entry. Must only be present if `dtstart_at` or `location` are set. Type: `datetime`
`dtstart_at`	The starting time of an appointment. The activity will be shown as a calendar entry. Must only be present if `dtend_at` or `location` are set. Type: `datetime`
`location`	The location of the appointment Type: `string`
`contact_ids`	The list of the contacts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`email_cc`	Additional email addresses (comma-separated). To have them receive notifications, add this field to the `notification_email_to` template. Type: `string`
`state`	Activity state (one of the states of its type) Type: `string`
`tags`	The list of the tags associated with the activity Type: `array`
`title`	The activity title Type: `string`
`comments`	The list of comments. An activity can have any number of comments. Comments are represented inline in the activity resource. They are append-only. Use the attributes `comment_notes`, `comment_attachments` etc. to append a new comment to the activity. It is not possible to edit or delete existing comments. Adding a comment updates `updated_at` and `version` in the activity. A comment has the following fields: `contact_id`: The comment author's ID. `notes`: The comment text. `attachments`: The comment attachments. The array of `strings` contains attachment IDs. `published`: Publicly visible? `boolean` `updated_at`: Comment date (`datetime`) `updated_by`: Login of the comment author Type: `array`

HTTP Response Code: 200

POST /api2/activities — Create an activity

Request

Optional Parameters:

Name	Description
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`account_ids`	The list of the accounts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`dtend_at`	The ending time of an appointment. The activity is shown as a calendar entry. Must only be present if `dtstart_at` or `location` are set. Type: `datetime`
`dtstart_at`	The starting time of an appointment. The activity will be shown as a calendar entry. Must only be present if `dtend_at` or `location` are set. Type: `datetime`
`location`	The location of the appointment Type: `string`
`contact_ids`	The list of the contacts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`email_cc`	Additional email addresses (comma-separated). To have them receive notifications, add this field to the `notification_email_to` template. Type: `string`
`state`	Activity state (one of the states of its type) Type: `string`
`tags`	The list of the tags associated with the activity Type: `array`
`title`	The activity title Type: `string`
`comment_attachments`	New comment attachment IDs Type: `array`
`comment_contact_id`	When adding a comment, the ID of the contact person concerned can be specified using this field (can be set only). Type: `string`
`comment_notes`	New comment text Type: `string`
`comment_published`	The new comment is visible to the `contact_id` person of the activity and is sent to the email recipients. Type: `boolean`

Response

The representation of the created activity

Parameters:

Name	Description
`base_type`	base_type is always Activity. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type ID of the item Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_ids`	The list of the accounts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`dtend_at`	The ending time of an appointment. The activity is shown as a calendar entry. Must only be present if `dtstart_at` or `location` are set. Type: `datetime`
`dtstart_at`	The starting time of an appointment. The activity will be shown as a calendar entry. Must only be present if `dtend_at` or `location` are set. Type: `datetime`
`location`	The location of the appointment Type: `string`
`contact_ids`	The list of the contacts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`email_cc`	Additional email addresses (comma-separated). To have them receive notifications, add this field to the `notification_email_to` template. Type: `string`
`state`	Activity state (one of the states of its type) Type: `string`
`tags`	The list of the tags associated with the activity Type: `array`
`title`	The activity title Type: `string`
`comments`	The list of comments. An activity can have any number of comments. Comments are represented inline in the activity resource. They are append-only. Use the attributes `comment_notes`, `comment_attachments` etc. to append a new comment to the activity. It is not possible to edit or delete existing comments. Adding a comment updates `updated_at` and `version` in the activity. A comment has the following fields: `contact_id`: The comment author's ID. `notes`: The comment text. `attachments`: The comment attachments. The array of `strings` contains attachment IDs. `published`: Publicly visible? `boolean` `updated_at`: Comment date (`datetime`) `updated_by`: Login of the comment author Type: `array`

HTTP Response Code: 201

PUT /api2/activities/:id — Update an activity

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name	Description
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`account_ids`	The list of the accounts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`dtend_at`	The ending time of an appointment. The activity is shown as a calendar entry. Must only be present if `dtstart_at` or `location` are set. Type: `datetime`
`dtstart_at`	The starting time of an appointment. The activity will be shown as a calendar entry. Must only be present if `dtend_at` or `location` are set. Type: `datetime`
`location`	The location of the appointment Type: `string`
`contact_ids`	The list of the contacts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`email_cc`	Additional email addresses (comma-separated). To have them receive notifications, add this field to the `notification_email_to` template. Type: `string`
`state`	Activity state (one of the states of its type) Type: `string`
`tags`	The list of the tags associated with the activity Type: `array`
`title`	The activity title Type: `string`
`comment_attachments`	New comment attachment IDs Type: `array`
`comment_contact_id`	When adding a comment, the ID of the contact person concerned can be specified using this field (can be set only). Type: `string`
`comment_notes`	New comment text Type: `string`
`comment_published`	The new comment is visible to the `contact_id` person of the activity and is sent to the email recipients. Type: `boolean`

Response

The representation of the updated activity

Parameters:

Name	Description
`base_type`	base_type is always Activity. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type ID of the item Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_ids`	The list of the accounts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`dtend_at`	The ending time of an appointment. The activity is shown as a calendar entry. Must only be present if `dtstart_at` or `location` are set. Type: `datetime`
`dtstart_at`	The starting time of an appointment. The activity will be shown as a calendar entry. Must only be present if `dtend_at` or `location` are set. Type: `datetime`
`location`	The location of the appointment Type: `string`
`contact_ids`	The list of the contacts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`email_cc`	Additional email addresses (comma-separated). To have them receive notifications, add this field to the `notification_email_to` template. Type: `string`
`state`	Activity state (one of the states of its type) Type: `string`
`tags`	The list of the tags associated with the activity Type: `array`
`title`	The activity title Type: `string`
`comments`	The list of comments. An activity can have any number of comments. Comments are represented inline in the activity resource. They are append-only. Use the attributes `comment_notes`, `comment_attachments` etc. to append a new comment to the activity. It is not possible to edit or delete existing comments. Adding a comment updates `updated_at` and `version` in the activity. A comment has the following fields: `contact_id`: The comment author's ID. `notes`: The comment text. `attachments`: The comment attachments. The array of `strings` contains attachment IDs. `published`: Publicly visible? `boolean` `updated_at`: Comment date (`datetime`) `updated_by`: Login of the comment author Type: `array`

HTTP Response Code: 200

DELETE /api2/activities/:id — Delete an activity

For optimistic locking, send the current version in an If-Match HTTP header.

Response

HTTP Response Code: 200

GET /api2/activities/:id/changes — Fetch the changelog of an activity

Request

Optional Parameters:

Name Description

Name	Description
`limit`	The number of changelog entries to fetch at most. The max. limit is 100. Type: `integer` Default: `10`

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The activity changelog

Parameters:

Name Description

Name	Description
`results`	The changelog entries in reverse order (newer -> older) Type: `array`

results

The changelog entries in reverse order (newer -> older)

Type: array

HTTP Response Code: 200

AttachmentStore

AttachmentStore represents actions related to activity attachments

POST /api2/attachment_store/generate_upload_permission — Generate an upload permission to upload a file directly to S3

For uploading a file, please proceed as follows.

Request an upload permission from the WebCRM. The response grants the client permission to upload a file to a given key on S3. This permission is valid for one hour.
Upload the file to the URL provided in the response, together with the fields as parameters. S3 itself then verifies the signature of these parameters prior to accepting the upload.
Attach the upload to a new activity comment by setting its commentattachments field to an array of upload IDs. The client may append filenames to the upload IDs for producing download URLs with proper file names later on. The format of commentattachments is: ["upload_id/filename.ext", ...], e.g. ["e13f0d960feeb2b29e9103b203ae03bd/screenshot.jpg"]. The WebCRM in turn translates these upload IDs to attachment IDs. Syntactically they look the same, upload IDs, however, are only temporary, whereas attachment ID are permanent. If the client appended a filename to the upload ID, the attachment ID will contain this filename, too. Otherwise, the attachment ID ends with "/file". Please note that the WebCRM replaces file name characters other than a-zA-Z0-9.+- with a dash. Multiple dashes will be joined into a single dash.
Later, when downloading the attachment, pass the attachment ID to a download URL request. The WebCRM returns a signed S3 URL that remains valid for 5 minutes.

Response

The upload permission

Parameters:

Name Description

Name	Description
`url`	The URL to which the attachment file data is uploaded Type: `string`
`fields`	Additional fields to include in the request when uploading to the URL Type: `object`
`upload_id`	A temporary ID associated with this upload. Use it when setting the `comment_attachments` field of an activity by means of the Activities API. Type: `string`

url

The URL to which the attachment file data is uploaded

Type: string

fields

Additional fields to include in the request when uploading to the URL

Type: object

upload_id

A temporary ID associated with this upload. Use it when setting the comment_attachments field of an activity by means of the Activities API.

Type: string

HTTP Response Code: 200

Example:

{ "url": "https://xyz.s3.amazonaws.com/", "fields": { "AWSAccessKeyId":"AKIAIDB73YRJUW2RAYXA", "key":"uploads/e13f0d960feeb2b29e9103b203ae03bd", "policy":"eyJleHBpcmF0aW9uIjoiMjAxMy0wOS0yNVQxNTozOToyNVoi...", "signature":"d9eVr1TPZ+Z9U0Fu6OmpVbbfLzI=" }, "upload_id": "e13f0d960feeb2b29e9103b203ae03bd" }

POST /api2/attachment_store/generate_download_url — Generate a download URL

Generates a download URL for the attachment file. The URL is presigned and valid for 5 minutes only. Hence, it is recommended to have such URLs generated on demand.

Request

Optional Parameters:

Name Description

Name	Description
`attachment_id`	An attachment ID taken from the attachments field inside the comments section of an activity. Type: `string` Example: `"627f069af6cfaf236393c6b7e40a12c5/84cb8263345bce4de2438ccea34f08fb/image.png"`

attachment_id

An attachment ID taken from the attachments field inside the comments section of an activity.

Type: string

Example:

"627f069af6cfaf236393c6b7e40a12c5/84cb8263345bce4de2438ccea34f08fb/image.png"

Response

The download URL

Parameters:

Name	Description
`base_type`	base_type is always Activity. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type ID of the item Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_ids`	The list of the accounts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`dtend_at`	The ending time of an appointment. The activity is shown as a calendar entry. Must only be present if `dtstart_at` or `location` are set. Type: `datetime`
`dtstart_at`	The starting time of an appointment. The activity will be shown as a calendar entry. Must only be present if `dtend_at` or `location` are set. Type: `datetime`
`location`	The location of the appointment Type: `string`
`contact_ids`	The list of the contacts associated with the activity Type: `array` Example: `["9762b2b4382f6bf34adbdeb21ce588aa"]`
`email_cc`	Additional email addresses (comma-separated). To have them receive notifications, add this field to the `notification_email_to` template. Type: `string`
`state`	Activity state (one of the states of its type) Type: `string`
`tags`	The list of the tags associated with the activity Type: `array`
`title`	The activity title Type: `string`
`comments`	The list of comments. An activity can have any number of comments. Comments are represented inline in the activity resource. They are append-only. Use the attributes `comment_notes`, `comment_attachments` etc. to append a new comment to the activity. It is not possible to edit or delete existing comments. Adding a comment updates `updated_at` and `version` in the activity. A comment has the following fields: `contact_id`: The comment author's ID. `notes`: The comment text. `attachments`: The comment attachments. The array of `strings` contains attachment IDs. `published`: Publicly visible? `boolean` `updated_at`: Comment date (`datetime`) `updated_by`: Login of the comment author Type: `array`

HTTP Response Code: 201

Example:

{ "url": "https://xyz.s3.amazonaws.com/attachments/84cb8263345bce4de2438ccea34f08fb/image.png?AWSAccessKeyId=...&Expires=...&Signature=..." }

Collection

Collection represents the WebCRM collection model

Attributes of Collection

Name	Description
`base_type`	base_type is always Collection. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Available for: `GET`, `POST`, `PUT` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always collection. Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`collection_type`	The collection type defines the base type of the items. It is one of: `contact`, `account`, `activity`, `event_contact`, `event`, `mailing_contact`. Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"contact"`
`event_id`	Mandatory in event contact collections, otherwise ignored Type: `string` Available for: `GET`, `POST`, `PUT`
`mailing_id`	Mandatory in mailing contact collections, otherwise ignored Type: `string` Available for: `GET`, `POST`, `PUT`
`title`	The title Type: `string` Available for: `GET`, `POST`, `PUT`
`filters`	Array of terms, each of which is an array of clauses. Each clause is an object with three properties: `field`, `condition`, `value`. Terms are OR expressions, clauses are AND expressions. A string value may contain "," to OR the parts. field values need to be prefixed with the lowercased base type, e.g. `contact.first_name`. Hint: specify a list of IDs to select all items with the given IDs, e.g. `"filters": [ [ { "field": "contact.id", "condition": "is_one_of", "value": ["id1", "id2"] } ] ]` Type: `array` Available for: `GET`, `POST`, `PUT` Example: `[ [ { "field": "contact.first_name", "condition": "contains_word_prefixes", "value": "Jo" }, { "field": "contact.last_name", "condition": "not_is_blank", "value": null }, { "field": "contact.gender", "condition": "equals", "value": ["M", "F"] } ] ]`
`output_ids_count`	The number of results of the last computation. 0 for uncomputed collections. May be stale if filters were changed or `compute_ids` was used since. Type: `integer` Available for: `GET`
`computation_started_at`	The timestamp of the starting time of the computation being performed. It is only set during the computation, and is set to `null` again afterwards. Type: `datetime` Available for: `GET`
`output_ids_computed_at`	The timestamp of the last computation Type: `datetime` Available for: `GET`

GET /api2/collections/:id — Fetch a collection

Response

The representation of the requested collection

Parameters:

Name	Description
`base_type`	base_type is always Collection. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always collection. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`collection_type`	The collection type defines the base type of the items. It is one of: `contact`, `account`, `activity`, `event_contact`, `event`, `mailing_contact`. Type: `string` Example: `"contact"`
`event_id`	Mandatory in event contact collections, otherwise ignored Type: `string`
`mailing_id`	Mandatory in mailing contact collections, otherwise ignored Type: `string`
`title`	The title Type: `string`
`filters`	Array of terms, each of which is an array of clauses. Each clause is an object with three properties: `field`, `condition`, `value`. Terms are OR expressions, clauses are AND expressions. A string value may contain "," to OR the parts. field values need to be prefixed with the lowercased base type, e.g. `contact.first_name`. Hint: specify a list of IDs to select all items with the given IDs, e.g. `"filters": [ [ { "field": "contact.id", "condition": "is_one_of", "value": ["id1", "id2"] } ] ]` Type: `array` Example: `[ [ { "field": "contact.first_name", "condition": "contains_word_prefixes", "value": "Jo" }, { "field": "contact.last_name", "condition": "not_is_blank", "value": null }, { "field": "contact.gender", "condition": "equals", "value": ["M", "F"] } ] ]`
`output_ids_count`	The number of results of the last computation. 0 for uncomputed collections. May be stale if filters were changed or `compute_ids` was used since. Type: `integer`
`computation_started_at`	The timestamp of the starting time of the computation being performed. It is only set during the computation, and is set to `null` again afterwards. Type: `datetime`
`output_ids_computed_at`	The timestamp of the last computation Type: `datetime`

HTTP Response Code: 200

POST /api2/collections — Create a collection

Request

Required Parameters:

Name	Description
`collection_type`	The collection type defines the base type of the items. It is one of: `contact`, `account`, `activity`, `event_contact`, `event`, `mailing_contact`. Type: `string` Example: `"contact"`
`event_id`	Mandatory in event contact collections, otherwise ignored Type: `string`
`mailing_id`	Mandatory in mailing contact collections, otherwise ignored Type: `string`
`title`	The title Type: `string`

Optional Parameters:

Name Description

custom_*

The custom attributes of a type. Custom attributes are user-defined.

Type: string, text, enum, multienum

Example:

"custom_category"

filters

Array of terms, each of which is an array of clauses. Each clause is an object with three properties: field, condition, value. Terms are OR expressions, clauses are AND expressions. A string value may contain "," to OR the parts. field values need to be prefixed with the lowercased base type, e.g. contact.first_name.

Hint: specify a list of IDs to select all items with the given IDs, e.g.

"filters": [ [ { "field": "contact.id", "condition": "is_one_of", "value": ["id1", "id2"] } ] ]

Type: array

Example:

[ [ { "field": "contact.first_name", "condition": "contains_word_prefixes", "value": "Jo" }, { "field": "contact.last_name", "condition": "not_is_blank", "value": null }, { "field": "contact.gender", "condition": "equals", "value": ["M", "F"] } ] ]

Response

The representation of the created collection

Parameters:

Name	Description
`base_type`	base_type is always Collection. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always collection. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`collection_type`	The collection type defines the base type of the items. It is one of: `contact`, `account`, `activity`, `event_contact`, `event`, `mailing_contact`. Type: `string` Example: `"contact"`
`event_id`	Mandatory in event contact collections, otherwise ignored Type: `string`
`mailing_id`	Mandatory in mailing contact collections, otherwise ignored Type: `string`
`title`	The title Type: `string`
`filters`	Array of terms, each of which is an array of clauses. Each clause is an object with three properties: `field`, `condition`, `value`. Terms are OR expressions, clauses are AND expressions. A string value may contain "," to OR the parts. field values need to be prefixed with the lowercased base type, e.g. `contact.first_name`. Hint: specify a list of IDs to select all items with the given IDs, e.g. `"filters": [ [ { "field": "contact.id", "condition": "is_one_of", "value": ["id1", "id2"] } ] ]` Type: `array` Example: `[ [ { "field": "contact.first_name", "condition": "contains_word_prefixes", "value": "Jo" }, { "field": "contact.last_name", "condition": "not_is_blank", "value": null }, { "field": "contact.gender", "condition": "equals", "value": ["M", "F"] } ] ]`
`output_ids_count`	The number of results of the last computation. 0 for uncomputed collections. May be stale if filters were changed or `compute_ids` was used since. Type: `integer`
`computation_started_at`	The timestamp of the starting time of the computation being performed. It is only set during the computation, and is set to `null` again afterwards. Type: `datetime`
`output_ids_computed_at`	The timestamp of the last computation Type: `datetime`

HTTP Response Code: 201

PUT /api2/collections/:id — Update a collection

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name	Description
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`collection_type`	The collection type defines the base type of the items. It is one of: `contact`, `account`, `activity`, `event_contact`, `event`, `mailing_contact`. Type: `string` Example: `"contact"`
`event_id`	Mandatory in event contact collections, otherwise ignored Type: `string`
`mailing_id`	Mandatory in mailing contact collections, otherwise ignored Type: `string`
`title`	The title Type: `string`
`filters`	Array of terms, each of which is an array of clauses. Each clause is an object with three properties: `field`, `condition`, `value`. Terms are OR expressions, clauses are AND expressions. A string value may contain "," to OR the parts. field values need to be prefixed with the lowercased base type, e.g. `contact.first_name`. Hint: specify a list of IDs to select all items with the given IDs, e.g. `"filters": [ [ { "field": "contact.id", "condition": "is_one_of", "value": ["id1", "id2"] } ] ]` Type: `array` Example: `[ [ { "field": "contact.first_name", "condition": "contains_word_prefixes", "value": "Jo" }, { "field": "contact.last_name", "condition": "not_is_blank", "value": null }, { "field": "contact.gender", "condition": "equals", "value": ["M", "F"] } ] ]`

Requirements:

Collection is currently not being computed

Response

The representation of the updated collection

Parameters:

Name	Description
`base_type`	base_type is always Collection. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always collection. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`collection_type`	The collection type defines the base type of the items. It is one of: `contact`, `account`, `activity`, `event_contact`, `event`, `mailing_contact`. Type: `string` Example: `"contact"`
`event_id`	Mandatory in event contact collections, otherwise ignored Type: `string`
`mailing_id`	Mandatory in mailing contact collections, otherwise ignored Type: `string`
`title`	The title Type: `string`
`filters`	Array of terms, each of which is an array of clauses. Each clause is an object with three properties: `field`, `condition`, `value`. Terms are OR expressions, clauses are AND expressions. A string value may contain "," to OR the parts. field values need to be prefixed with the lowercased base type, e.g. `contact.first_name`. Hint: specify a list of IDs to select all items with the given IDs, e.g. `"filters": [ [ { "field": "contact.id", "condition": "is_one_of", "value": ["id1", "id2"] } ] ]` Type: `array` Example: `[ [ { "field": "contact.first_name", "condition": "contains_word_prefixes", "value": "Jo" }, { "field": "contact.last_name", "condition": "not_is_blank", "value": null }, { "field": "contact.gender", "condition": "equals", "value": ["M", "F"] } ] ]`
`output_ids_count`	The number of results of the last computation. 0 for uncomputed collections. May be stale if filters were changed or `compute_ids` was used since. Type: `integer`
`computation_started_at`	The timestamp of the starting time of the computation being performed. It is only set during the computation, and is set to `null` again afterwards. Type: `datetime`
`output_ids_computed_at`	The timestamp of the last computation Type: `datetime`

HTTP Response Code: 200

DELETE /api2/collections/:id — Delete a collection

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Requirements:

Collection is currently not being computed

Response

HTTP Response Code: 200

PUT /api2/collections/:id/compute — Compute a collection

Determines the IDs of the items that match the filters using a background job. Use GET output_ids to fetch the IDs and mget to then fetch the items.

Request

Requirements:

Collection is currently not being computed
Filters have been specified

Response

The representation of the modified collection

Parameters:

Name	Description
`base_type`	base_type is always Collection. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always collection. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`collection_type`	The collection type defines the base type of the items. It is one of: `contact`, `account`, `activity`, `event_contact`, `event`, `mailing_contact`. Type: `string` Example: `"contact"`
`event_id`	Mandatory in event contact collections, otherwise ignored Type: `string`
`mailing_id`	Mandatory in mailing contact collections, otherwise ignored Type: `string`
`title`	The title Type: `string`
`filters`	Array of terms, each of which is an array of clauses. Each clause is an object with three properties: `field`, `condition`, `value`. Terms are OR expressions, clauses are AND expressions. A string value may contain "," to OR the parts. field values need to be prefixed with the lowercased base type, e.g. `contact.first_name`. Hint: specify a list of IDs to select all items with the given IDs, e.g. `"filters": [ [ { "field": "contact.id", "condition": "is_one_of", "value": ["id1", "id2"] } ] ]` Type: `array` Example: `[ [ { "field": "contact.first_name", "condition": "contains_word_prefixes", "value": "Jo" }, { "field": "contact.last_name", "condition": "not_is_blank", "value": null }, { "field": "contact.gender", "condition": "equals", "value": ["M", "F"] } ] ]`
`output_ids_count`	The number of results of the last computation. 0 for uncomputed collections. May be stale if filters were changed or `compute_ids` was used since. Type: `integer`
`computation_started_at`	The timestamp of the starting time of the computation being performed. It is only set during the computation, and is set to `null` again afterwards. Type: `datetime`
`output_ids_computed_at`	The timestamp of the last computation Type: `datetime`

HTTP Response Code: 200

GET /api2/collections/:id/output_ids — Get the computation result

Returns the list of the IDs that matched the filters

Response

The list of the IDs that matched the filters. Returns an empty list for uncomputed collections. May return a redirect to S3 instead of the data. May be stale if filters were changed after the latest computation.

HTTP Response Code: 200

Example:

[ '9762b2b4382f6bf34adbdeb21ce588aa', '4c562cc22b2dd164f353756526664589' ]

GET /api2/collections/:id/changes — Fetch the changelog of a collection

The log does not include changes to the output data

Request

Optional Parameters:

Name Description

Name	Description
`limit`	The number of changelog entries to fetch at most. The max. limit is 100. Type: `integer` Default: `10`

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The collection changelog

Parameters:

Name Description

Name	Description
`results`	The changelog entries in reverse order (newer -> older) Type: `array`

results

The changelog entries in reverse order (newer -> older)

Type: array

HTTP Response Code: 200

Contact

Contact represents the WebCRM contact model

Attributes of Contact

Name	Description
`base_type`	base_type is always Contact. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Available for: `GET`, `POST`, `PUT` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always contact. Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`account_id`	The ID of the associated account Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string` Available for: `GET`, `POST`, `PUT`
`last_name`	The last name of the contact Type: `string` Available for: `GET`, `POST`, `PUT`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"de"`
`job_title`	The job description of the contact Type: `string` Available for: `GET`, `POST`, `PUT`
`email`	The email address of the contact Type: `string` Available for: `GET`, `POST`, `PUT`
`phone`	The main phone number of the contact Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string` Available for: `GET`, `POST`, `PUT`
`fax`	The fax number of the contact Type: `string` Available for: `GET`, `POST`, `PUT`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string` Available for: `GET`, `POST`, `PUT`
`postalcode`	The postal code of the contact location Type: `string` Available for: `GET`, `POST`, `PUT`
`street_address`	The street name and building number of the contact location Type: `string` Available for: `GET`, `POST`, `PUT`
`locality`	The city in which the contact is based Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"Berlin"`
`extended_address`	An address extension Type: `string` Available for: `GET`, `POST`, `PUT`
`org_name_address`	Type: `string` Available for: `GET`, `POST`, `PUT`
`org_unit_address`	Type: `string` Available for: `GET`, `POST`, `PUT`
`tags`	A list of tags Type: `array` Available for: `GET`, `POST`, `PUT` Example: `["abc", "def"]`
`merged_into_id`	Type: `string` Available for: `GET`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean` Available for: `GET`, `POST`, `PUT`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean` Available for: `GET`, `POST`, `PUT`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean` Available for: `GET`, `POST`, `PUT`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string` Available for: `GET`, `POST`, `PUT`
`password_present`	Whether the contact has a password Type: `boolean` Available for: `GET`
`password_requested_at`	The timestamp of the most recent request for a new password token Type: `datetime` Available for: `GET`
`password_updated_at`	The timestamp of the most recent password renewal Type: `datetime` Available for: `GET`

GET /api2/contacts/:id — Fetch a contact

Response

The representation of the requested contact

Parameters:

Name	Description
`base_type`	base_type is always Contact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always contact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`last_name`	The last name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`merged_into_id`	Type: `string`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`
`password_present`	Whether the contact has a password Type: `boolean`
`password_requested_at`	The timestamp of the most recent request for a new password token Type: `datetime`
`password_updated_at`	The timestamp of the most recent password renewal Type: `datetime`

HTTP Response Code: 200

POST /api2/contacts — Create a contact

Request

Required Parameters:

Name Description

Name	Description
`last_name`	The last name of the contact Type: `string`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`

last_name

The last name of the contact

Type: string

language

The preferred language of the contact. One of the codes defined in the contact type.

Type: string

Example:

"de"

Optional Parameters:

Name	Description
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`

Response

The representation of the created contact

Parameters:

Name	Description
`base_type`	base_type is always Contact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always contact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`last_name`	The last name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`merged_into_id`	Type: `string`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`
`password_present`	Whether the contact has a password Type: `boolean`
`password_requested_at`	The timestamp of the most recent request for a new password token Type: `datetime`
`password_updated_at`	The timestamp of the most recent password renewal Type: `datetime`

HTTP Response Code: 201

PUT /api2/contacts/:id — Update a contact

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name	Description
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`last_name`	The last name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`

Response

The representation of the updated contact

Parameters:

Name	Description
`base_type`	base_type is always Contact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always contact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`last_name`	The last name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`merged_into_id`	Type: `string`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`
`password_present`	Whether the contact has a password Type: `boolean`
`password_requested_at`	The timestamp of the most recent request for a new password token Type: `datetime`
`password_updated_at`	The timestamp of the most recent password renewal Type: `datetime`

HTTP Response Code: 200

DELETE /api2/contacts/:id — Delete a contact

For optimistic locking, send the current version in an If-Match HTTP header.

Response

HTTP Response Code: 200

POST /api2/contacts/:id/merge_and_delete — Merge and delete a contact

Assigns the dependent docs/items of the contact with ID id to merge_into_id after deleting id.

Request

Required Parameters:

Name Description

merge_into_id

The ID of the contact to assign the dependent docs/items to

Type: string

Example:

"caba97c7f07801d57c148f977df26d62"

Requirements:

merge_into_id != id

Response

HTTP Response Code: 200

GET /api2/contacts/:id/changes — Fetch the changelog of a contact

Request

Optional Parameters:

Name Description

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The contact changelog

Parameters:

Name Description

results

The changelog entries in reverse order (newer -> older)

Type: array

Example:

HTTP Response Code: 200

PUT /api2/contacts/:id/clear_password — Clear the contact's password

Prevents the contact from logging in until a new password has been set

Response

The representation of the modified contact.

Parameters:

Name	Description
`base_type`	base_type is always Contact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always contact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`last_name`	The last name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`merged_into_id`	Type: `string`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`
`password_present`	Whether the contact has a password Type: `boolean`
`password_requested_at`	The timestamp of the most recent request for a new password token Type: `datetime`
`password_updated_at`	The timestamp of the most recent password renewal Type: `datetime`

HTTP Response Code: 200

POST /api2/contacts/:id/generate_password_token — Generate a password token

A project that uses this API could send an email to the contact. The mail should contain a link to the project web app. The link should contain the param ?token=.... It is the responsibility of the web app to parse the token param and pass it to PUT contacts/set_password_by_token. Tokens expire after 24 hours.

Request

Requirements:

Contact has a login

Response

The password token

Parameters:

Name	Description
`token`	Type: `string`

HTTP Response Code: 200

Example:

{ "token": "xyz" }

POST /api2/contacts/:id/send_password_token_email — Send an email containing a password token to the contact

Configure the password mail template to contain a link to the project web app. The link should contain the param ?token=.... It is the responsibility of the web app to parse the token param and pass it to PUT contacts/set_password_by_token. Tokens expire after 24h.

Request

Requirements:

Contact has a login
Contact has an email address

Response

An empty response

HTTP Response Code: 200

PUT /api2/contacts/:id/set_password — Set a new password

No questions asked. The API does not require to send the old password. In order to check the old password in the web app, use authenticate prior to setting the new password.

Request

Optional Parameters:

Name Description

password

The new password to set

Type: string

Requirements:

Contact has a login

Response

The representation of the modified contact

Parameters:

Name	Description
`base_type`	base_type is always Contact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always contact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`last_name`	The last name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`merged_into_id`	Type: `string`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`
`password_present`	Whether the contact has a password Type: `boolean`
`password_requested_at`	The timestamp of the most recent request for a new password token Type: `datetime`
`password_updated_at`	The timestamp of the most recent password renewal Type: `datetime`

HTTP Response Code: 200

PUT /api2/contacts/set_password_by_token — Set a new password by token

The contact is identified by means of the token.

Use case: contact clicks on a link (including a token) in an email to visit a password change page.

Request

Optional Parameters:

Name Description

password

The new password to set

Type: string

token

The token as acquired from generate_password_token or send_password_token_email.

Type: string

Requirements:

Contact has a login
Token has not expired

Response

The representation of the modified contact

Parameters:

Name	Description
`base_type`	base_type is always Contact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always contact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`last_name`	The last name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`merged_into_id`	Type: `string`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`
`password_present`	Whether the contact has a password Type: `boolean`
`password_requested_at`	The timestamp of the most recent request for a new password token Type: `datetime`
`password_updated_at`	The timestamp of the most recent password renewal Type: `datetime`

HTTP Response Code: 200

PUT /api2/contacts/authenticate — Authenticate a contact by means of a login and a password

Request

Optional Parameters:

Name Description

login

The login of the contact

Type: string

password

The contact's password

Type: string

Requirements:

Response

The representation of the contact

Parameters:

Name	Description
`base_type`	base_type is always Contact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	The custom attributes of a type. Custom attributes are user-defined. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always contact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`account_id`	The ID of the associated account Type: `string` Example: `"9762b2b4382f6bf34adbdeb21ce588aa"`
`name_prefix`	A string to prepend to the name Type: `string` Example: `"Dr."`
`first_name`	The first name of the contact Type: `string`
`last_name`	The last name of the contact Type: `string`
`gender`	The gender of the contact. One of `M` (male), `F` (female), `N` (unknown). Type: `string` Example: `"F"`
`language`	The preferred language of the contact. One of the codes defined in the contact type. Type: `string` Example: `"de"`
`job_title`	The job description of the contact Type: `string`
`email`	The email address of the contact Type: `string`
`phone`	The main phone number of the contact Type: `string` Example: `"+49 30 123456789"`
`mobile_phone`	The main mobile phone number of the contact Type: `string`
`fax`	The fax number of the contact Type: `string`
`country`	The country in which the contact is based (stored in uppercase) Type: `string` Example: `"GERMANY"`
`region`	The region in which the contact is based Type: `string`
`postalcode`	The postal code of the contact location Type: `string`
`street_address`	The street name and building number of the contact location Type: `string`
`locality`	The city in which the contact is based Type: `string` Example: `"Berlin"`
`extended_address`	An address extension Type: `string`
`org_name_address`	Type: `string`
`org_unit_address`	Type: `string`
`tags`	A list of tags Type: `array` Example: `["abc", "def"]`
`merged_into_id`	Type: `string`
`want_geo_location`	Whether to look up the geo coordinates of the address Type: `boolean`
`want_phonecall`	Whether the contact wants to receive phone calls Type: `boolean`
`want_snailmail`	Whether the contact wants to receive snail mail Type: `boolean`
`login`	The login used to authenticate. Must be unique in the tenant. Type: `string`
`password_present`	Whether the contact has a password Type: `boolean`
`password_requested_at`	The timestamp of the most recent request for a new password token Type: `datetime`
`password_updated_at`	The timestamp of the most recent password renewal Type: `datetime`

HTTP Response Code: 200

EventContact

EventContact represents the WebCRM event participation model

Attributes of EventContact

Name	Description
`base_type`	base_type is always EventContact. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	Custom attributes are defined in the associated event. Type: `string`, `text`, `enum`, `multienum` Available for: `GET`, `POST`, `PUT` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	typeid is always eventcontact. Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`contact_id`	The ID of the contact person concerned Type: `string` Available for: `GET`, `POST`
`event_id`	The ID of the event concerned Type: `string` Available for: `GET`, `POST`
`state`	Event participation state of the person. One of: `unregistered`, `registered`, `attended`, `refused`, `noshow`. Type: `string` Available for: `GET`, `POST`, `PUT`
`state_updated_at`	Timestamp of the most recent update of the participant's state. Type: `datetime` Available for: `GET`

GET /api2/event_contacts/:id — Fetch an event contact

Response

The representation of the requested event contact

Parameters:

Name	Description
`base_type`	base_type is always EventContact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	Custom attributes are defined in the associated event. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	typeid is always eventcontact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`contact_id`	The ID of the contact person concerned Type: `string`
`event_id`	The ID of the event concerned Type: `string`
`state`	Event participation state of the person. One of: `unregistered`, `registered`, `attended`, `refused`, `noshow`. Type: `string`
`state_updated_at`	Timestamp of the most recent update of the participant's state. Type: `datetime`

HTTP Response Code: 200

POST /api2/event_contacts — Create an event_contact

Request

Optional Parameters:

Name	Description
`custom_*`	Custom attributes are defined in the associated event. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`contact_id`	The ID of the contact person concerned Type: `string`
`event_id`	The ID of the event concerned Type: `string`
`state`	Event participation state of the person. One of: `unregistered`, `registered`, `attended`, `refused`, `noshow`. Type: `string`

Response

The representation of the created event contact

Parameters:

Name	Description
`base_type`	base_type is always EventContact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	Custom attributes are defined in the associated event. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	typeid is always eventcontact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`contact_id`	The ID of the contact person concerned Type: `string`
`event_id`	The ID of the event concerned Type: `string`
`state`	Event participation state of the person. One of: `unregistered`, `registered`, `attended`, `refused`, `noshow`. Type: `string`
`state_updated_at`	Timestamp of the most recent update of the participant's state. Type: `datetime`

HTTP Response Code: 201

PUT /api2/event_contacts/:id — Update an event contact

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name Description

custom_*

Custom attributes are defined in the associated event.

Type: string, text, enum, multienum

Example:

"custom_category"

state

Event participation state of the person.

One of: unregistered, registered, attended, refused, noshow.

Type: string

Response

The representation of the updated event contact

Parameters:

Name	Description
`base_type`	base_type is always EventContact. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	Custom attributes are defined in the associated event. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	typeid is always eventcontact. Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`contact_id`	The ID of the contact person concerned Type: `string`
`event_id`	The ID of the event concerned Type: `string`
`state`	Event participation state of the person. One of: `unregistered`, `registered`, `attended`, `refused`, `noshow`. Type: `string`
`state_updated_at`	Timestamp of the most recent update of the participant's state. Type: `datetime`

HTTP Response Code: 200

DELETE /api2/event_contacts/:id — Delete an event contact

For optimistic locking, send the current version in an If-Match HTTP header.

Response

HTTP Response Code: 200

GET /api2/event_contacts/:id/changes — Fetch the changelog of an event contact

Request

Optional Parameters:

Name Description

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The event contact changelog

Parameters:

Name Description

results

The changelog entries in reverse order (newer -> older)

Type: array

HTTP Response Code: 200

Event

Event represents the WebCRM event model

Attributes of Event

Name	Description
`base_type`	base_type is always Event. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	Custom attributes of the type with the specified type_id. Type: `string`, `text`, `enum`, `multienum` Available for: `GET`, `POST`, `PUT` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type determines which custom attributes the event has Type: `string` Available for: `GET`, `POST` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`attribute_definitions`	A hash of attribute definitions for the event contacts of this event. The keys are the attribute names, the values are the respective definitions. Custom attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Type: `object` Available for: `GET`, `POST`, `PUT` Example: `{ "custom_foo": { "title": "...", "attribute_type": "string", "mandatory": false, "max_length": 10, "valid_values": ['val1', 'val2'], }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Available for: `GET`, `POST`, `PUT` Example: `["custom_foo", "custom_bar"]`
`dtstart_at`	The timestamp of the beginning of the event Type: `datetime` Available for: `GET`, `POST`, `PUT`
`dtend_at`	The timestamp of the end of the event Type: `datetime` Available for: `GET`, `POST`, `PUT`
`event_set`	A string that can be used to categorize the event Type: `string` Available for: `GET`, `POST`, `PUT` Example: `"meeting"`
`location`	The place at which the event takes place Type: `string` Available for: `GET`, `POST`, `PUT`
`title`	The title of the event Type: `string` Available for: `GET`, `POST`, `PUT`

GET /api2/events/:id — Fetch an event

Response

The representation of the requested event

Parameters:

Name	Description
`base_type`	base_type is always Event. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	Custom attributes of the type with the specified type_id. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type determines which custom attributes the event has Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`attribute_definitions`	A hash of attribute definitions for the event contacts of this event. The keys are the attribute names, the values are the respective definitions. Custom attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Type: `object` Example: `{ "custom_foo": { "title": "...", "attribute_type": "string", "mandatory": false, "max_length": 10, "valid_values": ['val1', 'val2'], }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`
`dtstart_at`	The timestamp of the beginning of the event Type: `datetime`
`dtend_at`	The timestamp of the end of the event Type: `datetime`
`event_set`	A string that can be used to categorize the event Type: `string` Example: `"meeting"`
`location`	The place at which the event takes place Type: `string`
`title`	The title of the event Type: `string`

HTTP Response Code: 200

POST /api2/events — Create an event

Request

Required Parameters:

Name	Description
`type_id`	The type determines which custom attributes the event has Type: `string` Example: `"support-case"`
`dtstart_at`	The timestamp of the beginning of the event Type: `datetime`
`dtend_at`	The timestamp of the end of the event Type: `datetime`
`title`	The title of the event Type: `string`

Optional Parameters:

Name	Description
`custom_*`	Custom attributes of the type with the specified type_id. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`attribute_definitions`	A hash of attribute definitions for the event contacts of this event. The keys are the attribute names, the values are the respective definitions. Custom attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Type: `object` Example: `{ "custom_foo": { "title": "...", "attribute_type": "string", "mandatory": false, "max_length": 10, "valid_values": ['val1', 'val2'], }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`
`event_set`	A string that can be used to categorize the event Type: `string` Example: `"meeting"`
`location`	The place at which the event takes place Type: `string`

Response

The representation of the created event

Parameters:

Name	Description
`base_type`	base_type is always Event. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	Custom attributes of the type with the specified type_id. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type determines which custom attributes the event has Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`attribute_definitions`	A hash of attribute definitions for the event contacts of this event. The keys are the attribute names, the values are the respective definitions. Custom attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Type: `object` Example: `{ "custom_foo": { "title": "...", "attribute_type": "string", "mandatory": false, "max_length": 10, "valid_values": ['val1', 'val2'], }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`
`dtstart_at`	The timestamp of the beginning of the event Type: `datetime`
`dtend_at`	The timestamp of the end of the event Type: `datetime`
`event_set`	A string that can be used to categorize the event Type: `string` Example: `"meeting"`
`location`	The place at which the event takes place Type: `string`
`title`	The title of the event Type: `string`

HTTP Response Code: 201

PUT /api2/events/:id — Update an event

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name	Description
`custom_*`	Custom attributes of the type with the specified type_id. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`attribute_definitions`	A hash of attribute definitions for the event contacts of this event. The keys are the attribute names, the values are the respective definitions. Custom attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Type: `object` Example: `{ "custom_foo": { "title": "...", "attribute_type": "string", "mandatory": false, "max_length": 10, "valid_values": ['val1', 'val2'], }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`
`dtstart_at`	The timestamp of the beginning of the event Type: `datetime`
`dtend_at`	The timestamp of the end of the event Type: `datetime`
`event_set`	A string that can be used to categorize the event Type: `string` Example: `"meeting"`
`location`	The place at which the event takes place Type: `string`
`title`	The title of the event Type: `string`

Response

The representation of the updated event

Parameters:

Name	Description
`base_type`	base_type is always Event. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_*`	Custom attributes of the type with the specified type_id. Type: `string`, `text`, `enum`, `multienum` Example: `"custom_category"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	The type determines which custom attributes the event has Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`attribute_definitions`	A hash of attribute definitions for the event contacts of this event. The keys are the attribute names, the values are the respective definitions. Custom attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Type: `object` Example: `{ "custom_foo": { "title": "...", "attribute_type": "string", "mandatory": false, "max_length": 10, "valid_values": ['val1', 'val2'], }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`
`dtstart_at`	The timestamp of the beginning of the event Type: `datetime`
`dtend_at`	The timestamp of the end of the event Type: `datetime`
`event_set`	A string that can be used to categorize the event Type: `string` Example: `"meeting"`
`location`	The place at which the event takes place Type: `string`
`title`	The title of the event Type: `string`

HTTP Response Code: 200

DELETE /api2/events/:id — Delete an event

For optimistic locking, send the current version in an If-Match HTTP header.

Response

HTTP Response Code: 200

GET /api2/events/:id/changes — Fetch the changelog of an event

Request

Optional Parameters:

Name Description

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The event changelog

Parameters:

Name Description

results

The changelog entries in reverse order (newer -> older)

Type: array

HTTP Response Code: 200

Mailing

Mailing represents the WebCRM mailing model

Attributes of Mailing

Name	Description
`base_type`	base_type is always Mailing. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of an item Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`text_body`	Plain text content of the mailing Type: `string` Available for: `GET`, `POST`, `PUT`
`html_body`	HTML content of the mailing Type: `string` Available for: `GET`, `POST`, `PUT`
`planned_release_at`	Timestamp of the point in time the mailing is expected to be released. Mailings are not sent out automatically if the date arrives. Type: `datetime` Available for: `GET`, `POST`, `PUT`
`email_from`	Sender address of the emails Type: `string` Available for: `GET`, `POST`, `PUT`
`email_reply_to`	Address to which replies are sent Type: `string` Available for: `GET`, `POST`, `PUT`
`email_subject`	Subject of the emails Type: `string` Available for: `GET`, `POST`, `PUT`
`consent_requirement`	One of `given`, `not_revoked`, `none`. This field defines how the WebCRM should behave if a mailing recipient has not given consent. If the consent requirement is `given`, the WebCRM sends only to recipients who have given their consent. If the consent requirement is `not_revoked`, the WebCRM sends only to recipients who have not revoked their consent (i.e. to all recipients with consent `given` or `unknown`). If the consent requirement is set to `none`, the mailing is sent to all planned mailing recipients, regardless of their expressed consent. Note that the WebCRM will never send mailings to inactive mailing recipients. Type: `string` Default: `given` Available for: `GET`, `POST`, `PUT`
`collection_id`	A collection of contacts or event contacts the mails will be sent to Type: `string` Available for: `GET`, `POST`, `PUT`
`event_id`	ID of the event associated with the mailing Type: `string` Available for: `GET`, `POST`, `PUT`
`released_at`	Timestamp of the release of the mailing Type: `datetime` Available for: `GET`
`released_by`	Login of the person who released the mailing Type: `string` Available for: `GET`
`title`	Mailing title Type: `string` Available for: `GET`, `POST`, `PUT`

GET /api2/mailings/:id — Fetch a mailing

Response

The representation of the requested mailing

Parameters:

Name	Description
`base_type`	base_type is always Mailing. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`text_body`	Plain text content of the mailing Type: `string`
`html_body`	HTML content of the mailing Type: `string`
`planned_release_at`	Timestamp of the point in time the mailing is expected to be released. Mailings are not sent out automatically if the date arrives. Type: `datetime`
`email_from`	Sender address of the emails Type: `string`
`email_reply_to`	Address to which replies are sent Type: `string`
`email_subject`	Subject of the emails Type: `string`
`consent_requirement`	One of `given`, `not_revoked`, `none`. This field defines how the WebCRM should behave if a mailing recipient has not given consent. If the consent requirement is `given`, the WebCRM sends only to recipients who have given their consent. If the consent requirement is `not_revoked`, the WebCRM sends only to recipients who have not revoked their consent (i.e. to all recipients with consent `given` or `unknown`). If the consent requirement is set to `none`, the mailing is sent to all planned mailing recipients, regardless of their expressed consent. Note that the WebCRM will never send mailings to inactive mailing recipients. Type: `string` Default: `given`
`collection_id`	A collection of contacts or event contacts the mails will be sent to Type: `string`
`event_id`	ID of the event associated with the mailing Type: `string`
`released_at`	Timestamp of the release of the mailing Type: `datetime`
`released_by`	Login of the person who released the mailing Type: `string`
`title`	Mailing title Type: `string`

HTTP Response Code: 200

POST /api2/mailings/:id/clone — Clone a mailing

Creates a new mailing by cloning this mailing. Specify all the attributes you want to overwrite. Afterwards, you can still modify the new mailing using update.

Response

The representation of the created mailing

Parameters:

Name	Description
`base_type`	base_type is always Mailing. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`text_body`	Plain text content of the mailing Type: `string`
`html_body`	HTML content of the mailing Type: `string`
`planned_release_at`	Timestamp of the point in time the mailing is expected to be released. Mailings are not sent out automatically if the date arrives. Type: `datetime`
`email_from`	Sender address of the emails Type: `string`
`email_reply_to`	Address to which replies are sent Type: `string`
`email_subject`	Subject of the emails Type: `string`
`consent_requirement`	One of `given`, `not_revoked`, `none`. This field defines how the WebCRM should behave if a mailing recipient has not given consent. If the consent requirement is `given`, the WebCRM sends only to recipients who have given their consent. If the consent requirement is `not_revoked`, the WebCRM sends only to recipients who have not revoked their consent (i.e. to all recipients with consent `given` or `unknown`). If the consent requirement is set to `none`, the mailing is sent to all planned mailing recipients, regardless of their expressed consent. Note that the WebCRM will never send mailings to inactive mailing recipients. Type: `string` Default: `given`
`collection_id`	A collection of contacts or event contacts the mails will be sent to Type: `string`
`event_id`	ID of the event associated with the mailing Type: `string`
`released_at`	Timestamp of the release of the mailing Type: `datetime`
`released_by`	Login of the person who released the mailing Type: `string`
`title`	Mailing title Type: `string`

HTTP Response Code: 201

POST /api2/mailings — Create a mailing

Request

Required Parameters:

Name Description

title

Mailing title

Type: string

Optional Parameters:

Name	Description
`text_body`	Plain text content of the mailing Type: `string`
`html_body`	HTML content of the mailing Type: `string`
`planned_release_at`	Timestamp of the point in time the mailing is expected to be released. Mailings are not sent out automatically if the date arrives. Type: `datetime`
`email_from`	Sender address of the emails Type: `string`
`email_reply_to`	Address to which replies are sent Type: `string`
`email_subject`	Subject of the emails Type: `string`
`consent_requirement`	One of `given`, `not_revoked`, `none`. This field defines how the WebCRM should behave if a mailing recipient has not given consent. If the consent requirement is `given`, the WebCRM sends only to recipients who have given their consent. If the consent requirement is `not_revoked`, the WebCRM sends only to recipients who have not revoked their consent (i.e. to all recipients with consent `given` or `unknown`). If the consent requirement is set to `none`, the mailing is sent to all planned mailing recipients, regardless of their expressed consent. Note that the WebCRM will never send mailings to inactive mailing recipients. Type: `string` Default: `given`
`collection_id`	A collection of contacts or event contacts the mails will be sent to Type: `string`
`event_id`	ID of the event associated with the mailing Type: `string`

Response

The representation of the created mailing

Parameters:

Name	Description
`base_type`	base_type is always Mailing. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`text_body`	Plain text content of the mailing Type: `string`
`html_body`	HTML content of the mailing Type: `string`
`planned_release_at`	Timestamp of the point in time the mailing is expected to be released. Mailings are not sent out automatically if the date arrives. Type: `datetime`
`email_from`	Sender address of the emails Type: `string`
`email_reply_to`	Address to which replies are sent Type: `string`
`email_subject`	Subject of the emails Type: `string`
`consent_requirement`	One of `given`, `not_revoked`, `none`. This field defines how the WebCRM should behave if a mailing recipient has not given consent. If the consent requirement is `given`, the WebCRM sends only to recipients who have given their consent. If the consent requirement is `not_revoked`, the WebCRM sends only to recipients who have not revoked their consent (i.e. to all recipients with consent `given` or `unknown`). If the consent requirement is set to `none`, the mailing is sent to all planned mailing recipients, regardless of their expressed consent. Note that the WebCRM will never send mailings to inactive mailing recipients. Type: `string` Default: `given`
`collection_id`	A collection of contacts or event contacts the mails will be sent to Type: `string`
`event_id`	ID of the event associated with the mailing Type: `string`
`released_at`	Timestamp of the release of the mailing Type: `datetime`
`released_by`	Login of the person who released the mailing Type: `string`
`title`	Mailing title Type: `string`

HTTP Response Code: 201

PUT /api2/mailings/:id — Update a mailing

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name	Description
`text_body`	Plain text content of the mailing Type: `string`
`html_body`	HTML content of the mailing Type: `string`
`planned_release_at`	Timestamp of the point in time the mailing is expected to be released. Mailings are not sent out automatically if the date arrives. Type: `datetime`
`email_from`	Sender address of the emails Type: `string`
`email_reply_to`	Address to which replies are sent Type: `string`
`email_subject`	Subject of the emails Type: `string`
`consent_requirement`	One of `given`, `not_revoked`, `none`. This field defines how the WebCRM should behave if a mailing recipient has not given consent. If the consent requirement is `given`, the WebCRM sends only to recipients who have given their consent. If the consent requirement is `not_revoked`, the WebCRM sends only to recipients who have not revoked their consent (i.e. to all recipients with consent `given` or `unknown`). If the consent requirement is set to `none`, the mailing is sent to all planned mailing recipients, regardless of their expressed consent. Note that the WebCRM will never send mailings to inactive mailing recipients. Type: `string` Default: `given`
`collection_id`	A collection of contacts or event contacts the mails will be sent to Type: `string`
`event_id`	ID of the event associated with the mailing Type: `string`
`title`	Mailing title Type: `string`

Response

The representation of the updated mailing

Parameters:

Name	Description
`base_type`	base_type is always Mailing. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`text_body`	Plain text content of the mailing Type: `string`
`html_body`	HTML content of the mailing Type: `string`
`planned_release_at`	Timestamp of the point in time the mailing is expected to be released. Mailings are not sent out automatically if the date arrives. Type: `datetime`
`email_from`	Sender address of the emails Type: `string`
`email_reply_to`	Address to which replies are sent Type: `string`
`email_subject`	Subject of the emails Type: `string`
`consent_requirement`	One of `given`, `not_revoked`, `none`. This field defines how the WebCRM should behave if a mailing recipient has not given consent. If the consent requirement is `given`, the WebCRM sends only to recipients who have given their consent. If the consent requirement is `not_revoked`, the WebCRM sends only to recipients who have not revoked their consent (i.e. to all recipients with consent `given` or `unknown`). If the consent requirement is set to `none`, the mailing is sent to all planned mailing recipients, regardless of their expressed consent. Note that the WebCRM will never send mailings to inactive mailing recipients. Type: `string` Default: `given`
`collection_id`	A collection of contacts or event contacts the mails will be sent to Type: `string`
`event_id`	ID of the event associated with the mailing Type: `string`
`released_at`	Timestamp of the release of the mailing Type: `datetime`
`released_by`	Login of the person who released the mailing Type: `string`
`title`	Mailing title Type: `string`

HTTP Response Code: 200

DELETE /api2/mailings/:id — Delete a mailing

For optimistic locking, send the current version in an If-Match HTTP header.

Response

HTTP Response Code: 200

GET /api2/mailings/:id/changes — Fetch the changelog of a mailing

Request

Optional Parameters:

Name Description

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The mailing changelog

Parameters:

Name Description

results

The changelog entries in reverse order (newer -> older)

Type: array

HTTP Response Code: 200

POST /api2/mailings/:id/render_preview — Render a mailing preview

Renders a mailing preview

Request

Optional Parameters:

Name Description

render_for_contact_id

Personalizes the preview for this contact (salutation, name etc.). This parameter is necessary for Liquid mailings, but unused for Scrivito mailings.

Type: string

Response

For Liquid mailings, the response contains email fields personalized in the context of the contact.

For Scrivito mailings, the response is not personalized. It does not contain the fields email_to and text_body.

Parameters:

Name	Description
`email_from`	Type: `string`
`email_reply_to`	Type: `string`
`email_subject`	Type: `string`
`email_to`	Type: `string`
`html_body`	Type: `string`
`text_body`	Type: `string`

HTTP Response Code: 200

Example:

# For Liquid mailing: { "email_from": "Marketing <marketing@example.com>", "email_reply_to": "reply@example.com", "email_subject": "Invitation to exhibition", "email_to": "john.doe@example.com", "html_body": "<h1>Welcome Mr. John Doe</h1>...", "text_body": "Welcome Mr. John Doe..." } # For Scrivito mailing: { "email_from": "Marketing <marketing@example.com>", "email_reply_to": "reply@example.com", "email_subject": "Invitation to exhibition", "html_body": "..." }

POST /api2/mailings/:id/send_single_email — Send a single email

Sends a mailing, e.g. a newsletter mailing, to a single person.

Use case: somebody registers for a newsletter, they should receive the most recent newsletter as well.

Request

Optional Parameters:

Name Description

recipient_contact_id

The contact to send a single email to

Type: string

Requirements:

Mailing has been released
Mailing attribute email_from has been registered as a valid sender
Contact recipient_contact_id has an email address
Contact recipient_contact_id wants to receive emails

Response

A status report

Parameters:

Name	Description
`message`	Type: `string`

HTTP Response Code: 200

Example:

{ "message": "email sent to $ADDR" }

POST /api2/mailings/:id/send_me_a_proof_email — Send a proof email

Sends a proof email (personalized for a contact) to the current user (the API user).

Request

Optional Parameters:

Name Description

render_for_contact_id

Personalize email for this contact (salutation, name etc.)

Type: string

Requirements:

Mailing attribute email_from has been registered as a valid sender
Current user has a valid email address

Response

A status report

Parameters:

Name	Description
`message`	Type: `string`

HTTP Response Code: 200

Example:

{ "message": "email sent to joe@example.com" }

POST /api2/mailings/:id/release — Release mailing

Sends the mailing to all recipient email addresses.

Marks the mailing as released (released_at, released_by) and also sets planned_release_at to now.

Request

Requirements:

Mailing has not been released or is no longer than 3 months released
Attribute email_from has been registered as a valid sender email address

Response

The representation of the updated mailing

Parameters:

Name	Description
`base_type`	base_type is always Mailing. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of an item Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`text_body`	Plain text content of the mailing Type: `string`
`html_body`	HTML content of the mailing Type: `string`
`planned_release_at`	Timestamp of the point in time the mailing is expected to be released. Mailings are not sent out automatically if the date arrives. Type: `datetime`
`email_from`	Sender address of the emails Type: `string`
`email_reply_to`	Address to which replies are sent Type: `string`
`email_subject`	Subject of the emails Type: `string`
`consent_requirement`	One of `given`, `not_revoked`, `none`. This field defines how the WebCRM should behave if a mailing recipient has not given consent. If the consent requirement is `given`, the WebCRM sends only to recipients who have given their consent. If the consent requirement is `not_revoked`, the WebCRM sends only to recipients who have not revoked their consent (i.e. to all recipients with consent `given` or `unknown`). If the consent requirement is set to `none`, the mailing is sent to all planned mailing recipients, regardless of their expressed consent. Note that the WebCRM will never send mailings to inactive mailing recipients. Type: `string` Default: `given`
`collection_id`	A collection of contacts or event contacts the mails will be sent to Type: `string`
`event_id`	ID of the event associated with the mailing Type: `string`
`released_at`	Timestamp of the release of the mailing Type: `datetime`
`released_by`	Login of the person who released the mailing Type: `string`
`title`	Mailing title Type: `string`

HTTP Response Code: 200

MailingDelivery

MailingDelivery represents a mailing delivery

Attributes of MailingDelivery

Name	Description
`bounced_at`	Timestamp of when the mailing delivery was bounced Type: `datetime` Available for: `GET`
`bounced_diagnostic_code`	The status code issued by the reporting MTA, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string` Available for: `GET`
`bounced_subtype`	The bounce subtype, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string` Available for: `GET`
`bounced_type`	The bounce type, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string` Available for: `GET`
`clicked_at`	Timestamp of when any tracked link in the email was clicked. Type: `datetime` Available for: `GET`
`clicked_links`	A list of clicked links. Type: `array` Available for: `GET`
`complained_at`	Timestamp of when a complaint was sent, i.e. the user clicked spam/junk or the mail server classified it as spam. Type: `datetime` Available for: `GET`
`complained_type`	The complaint feedback type, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#complaint-object Type: `string` Available for: `GET`
`complained_user_agent`	The user agent (the user's client) that reported the complaint, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#complaint-object Type: `string` Available for: `GET`
`contact_id`	The contact id of an associated contact. It will be automatically determined based on the email address. Type: `string` Available for: `GET`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`custom_data`	Custom properties attached to the mailing delivery for personalizing emails. The values can be inserted into the mailing content. Custom data is only available for Scrivito mailings. Type: `object` Available for: `GET`, `POST`, `PUT`
`delivered_at`	Timestamp of when the mailing delivery was delivered Type: `datetime` Available for: `GET`
`delivered_smtp_response`	The SMTP response message of the receiving mail server Type: `string` Available for: `GET`
`id`	Use the URL-encoded recipient email address as ID in the endpoint URL. Type: `string` Available for: `GET`
`mailing_id`	ID of the mailing this delivery belongs to Type: `string` Available for: `GET`
`opened_at`	Timestamp of when the email was opened Type: `datetime` Available for: `GET`
`processed_at`	Timestamp of when the mailing delivery was processed Type: `datetime` Available for: `GET`
`processing_error`	The error message in case processing failed Type: `string` Available for: `GET`
`released_at`	Timestamp of when the mailing delivery was released Type: `datetime` Available for: `GET`
`skipped`	Whether the sending of the email was skipped. This happens if the recipient email address opted out from receiving emails or previous deliveries bounced permanently. Type: `boolean` Available for: `GET`
`unsubscribed_at`	Timestamp of when the recipient unsubscribed from receiving further emails Type: `datetime` Available for: `GET`
`updated_at`	The timestamp of the last change made to the item. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`

GET /api2/mailings/:mailing_id/mailing_deliveries — Fetch all mailing deliveries of a mailing

Returns the list of mailing deliveries that belong to the mailing.

Request

Optional Parameters:

Name Description

since

A timestamp to filter deliveries by. Only mailing deliveries that were modified after or at this time are returned.

Type: datetime

Example:

"2014-01-01T00:00:00Z"

Requirements:

Mailing has not been deleted

Response

The shortened representation of all deliveries of the mailing sorted by id. Use the updated_at timestamp to determine if you need to fetch the details.

HTTP Response Code: 200

Example:

[ { "id": "abc@example.com", "updated_at": "2020-10-21T14:45:07Z" }, { "id": "def@example.com", "updated_at": "2020-10-21T14:43:55Z" } ]

GET /api2/mailings/:mailing_id/mailing_deliveries/:id — Fetch a mailing delivery

Request

Requirements:

Mailing has not been deleted

Response

The representation of the mailing delivery

Parameters:

Name	Description
`bounced_at`	Timestamp of when the mailing delivery was bounced Type: `datetime`
`bounced_diagnostic_code`	The status code issued by the reporting MTA, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string`
`bounced_subtype`	The bounce subtype, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string`
`bounced_type`	The bounce type, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string`
`clicked_at`	Timestamp of when any tracked link in the email was clicked. Type: `datetime`
`clicked_links`	A list of clicked links. Type: `array`
`complained_at`	Timestamp of when a complaint was sent, i.e. the user clicked spam/junk or the mail server classified it as spam. Type: `datetime`
`complained_type`	The complaint feedback type, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#complaint-object Type: `string`
`complained_user_agent`	The user agent (the user's client) that reported the complaint, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#complaint-object Type: `string`
`contact_id`	The contact id of an associated contact. It will be automatically determined based on the email address. Type: `string`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_data`	Custom properties attached to the mailing delivery for personalizing emails. The values can be inserted into the mailing content. Custom data is only available for Scrivito mailings. Type: `object`
`delivered_at`	Timestamp of when the mailing delivery was delivered Type: `datetime`
`delivered_smtp_response`	The SMTP response message of the receiving mail server Type: `string`
`id`	Use the URL-encoded recipient email address as ID in the endpoint URL. Type: `string`
`mailing_id`	ID of the mailing this delivery belongs to Type: `string`
`opened_at`	Timestamp of when the email was opened Type: `datetime`
`processed_at`	Timestamp of when the mailing delivery was processed Type: `datetime`
`processing_error`	The error message in case processing failed Type: `string`
`released_at`	Timestamp of when the mailing delivery was released Type: `datetime`
`skipped`	Whether the sending of the email was skipped. This happens if the recipient email address opted out from receiving emails or previous deliveries bounced permanently. Type: `boolean`
`unsubscribed_at`	Timestamp of when the recipient unsubscribed from receiving further emails Type: `datetime`
`updated_at`	The timestamp of the last change made to the item. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`

HTTP Response Code: 200

Example:

{ "bounced_at": "2020-10-21T15:45:07Z", "bounced_diagnostic_code": "smtp; 552 5.5.2 Mailbox full", "bounced_subtype": "MailboxFull", "bounced_type": "Transient", "clicked_at": "2020-10-21T15:45:07Z", "clicked_links": [ { "clicked_at": "2020-10-21T15:45:07Z", "title": "The Link Title", "url": "http://example.com" }, { ... } ], "complained_at": "2020-10-21T15:45:07Z", "complained_type": "abuse", "complained_user_agent": "the user agent", "contact_id": "950b3f7d33f2ae67b842ed1572f22b13", "created_at": "2020-10-21T13:45:07Z", "custom_data": { "salutation": "Mr. Doe" }, "delivered_at": "2020-10-21T15:45:07Z", "delivered_smtp_response": "250 2.0.0 OK 1594292034 b13si2065370", "id": "john.doe@example.com", "mailing_id": "04bc2c6257aa5d8bac34e6e1e828e8e2", "opened_at": "2020-10-21T15:45:07Z", "processed_at": "2020-10-21T15:45:07Z", "processing_error": "an error", "released_at": "2020-10-21T15:45:07Z", "skipped": false, "unsubscribed_at": "2020-10-21T15:45:07Z", "updated_at": "2020-10-21T14:45:07Z", "version": 2 }

PUT /api2/mailings/:mailing_id/mailing_deliveries/:id — Create or update a mailing delivery

If a mailing delivery for the specified id (email address) already exists, it will be updated instead.

Request

Optional Parameters:

Name Description

custom_data

Custom properties attached to the mailing delivery for personalizing emails. The values can be inserted into the mailing content. Custom data is only available for Scrivito mailings.

Type: object

Requirements:

Mailing has not been deleted

Response

The representation of the created or updated mailing delivery

Parameters:

Name	Description
`bounced_at`	Timestamp of when the mailing delivery was bounced Type: `datetime`
`bounced_diagnostic_code`	The status code issued by the reporting MTA, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string`
`bounced_subtype`	The bounce subtype, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string`
`bounced_type`	The bounce type, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#bounce-types Type: `string`
`clicked_at`	Timestamp of when any tracked link in the email was clicked. Type: `datetime`
`clicked_links`	A list of clicked links. Type: `array`
`complained_at`	Timestamp of when a complaint was sent, i.e. the user clicked spam/junk or the mail server classified it as spam. Type: `datetime`
`complained_type`	The complaint feedback type, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#complaint-object Type: `string`
`complained_user_agent`	The user agent (the user's client) that reported the complaint, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html#complaint-object Type: `string`
`contact_id`	The contact id of an associated contact. It will be automatically determined based on the email address. Type: `string`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`custom_data`	Custom properties attached to the mailing delivery for personalizing emails. The values can be inserted into the mailing content. Custom data is only available for Scrivito mailings. Type: `object`
`delivered_at`	Timestamp of when the mailing delivery was delivered Type: `datetime`
`delivered_smtp_response`	The SMTP response message of the receiving mail server Type: `string`
`id`	Use the URL-encoded recipient email address as ID in the endpoint URL. Type: `string`
`mailing_id`	ID of the mailing this delivery belongs to Type: `string`
`opened_at`	Timestamp of when the email was opened Type: `datetime`
`processed_at`	Timestamp of when the mailing delivery was processed Type: `datetime`
`processing_error`	The error message in case processing failed Type: `string`
`released_at`	Timestamp of when the mailing delivery was released Type: `datetime`
`skipped`	Whether the sending of the email was skipped. This happens if the recipient email address opted out from receiving emails or previous deliveries bounced permanently. Type: `boolean`
`unsubscribed_at`	Timestamp of when the recipient unsubscribed from receiving further emails Type: `datetime`
`updated_at`	The timestamp of the last change made to the item. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`

HTTP Response Code: 200

DELETE /api2/mailings/:mailing_id/mailing_deliveries/:id — Delete a mailing delivery

Request

Requirements:

Mailing has not been deleted
Mailing delivery has not been released

Response

Deleting a mailing delivery is irreversible.

HTTP Response Code: 200

MailingRecipient

MailingRecipient represents a mailing recipient email address

Attributes of MailingRecipient

Name	Description
`base_type`	base_type is always MailingRecipient Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`id`	use the url-encoded recipient email address as ID Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing-recipient Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`active`	When sending mailings, this flag determines whether the WebCRM sends emails to this address. Type: `boolean` Available for: `GET`, `POST`, `PUT`
`consent`	If the user has given their consent, the value is "given". If the user has revoked their consent, the value is "revoked". Otherwise the value is "unknown". Type: `string` Available for: `GET`, `POST`, `PUT`
`topic_names`	A list of subscribed topic names. Type: `array` Available for: `GET`, `POST`, `PUT`
`topic_names_unsubscribed`	A list of unsubscribed topic names. The unsubscribed topic names are computed as the difference set between all available topic names and the subscribed topic names. Type: `array` Available for: `GET`
`edit_reason`	A sentence that describes why the activeness/consent/subscriptions were changed, e.g. "recipient email address used the subscription form on www.foo.com". The text will be logged in the recipient email address. See `consent_logs`. Type: `string` Available for: `GET`, `POST`, `PUT`
`consent_logs`	An array of log entries. Every entry is a hash with the keys `at`, `description` and `changes`. Type: `array` Available for: `GET`
`complained_at`	Type: `datetime` Available for: `GET`
`permanent_bounced_at`	Type: `datetime` Available for: `GET`
`consent_given_at`	Type: `datetime` Available for: `GET`
`consent_revoked_at`	Type: `datetime` Available for: `GET`

GET /api2/mailing_recipients — Fetch all mailing recipient email addresses

Returns the list of mailing recipient email addresses.

Request

Optional Parameters:

Name Description

since

A timestamp to filter recipients by. Only those that were modified after or at this time are returned.

Type: datetime

Example:

"2014-01-01T00:00:00Z"

Response

The representation of up to 100 mailing recipients sorted by update time. If no since param is given, the list starts with the oldest updated mailing recipient. To fetch more mailing recipients, query this endpoint again with a later since param.

HTTP Response Code: 200

Example:

[ { "active": true, "complained_at": null, "consent": "given", "consent_logs": [], "consent_given_at": "2021-01-04T12:25:07Z", "consent_revoked_at": null, "created_at": "2020-12-08T10:13:56Z", "created_by": "user1", "id": "john.doe@example.com", "permanent_bounced_at": null, "topic_names_unsubscribed": ["Product-Info"], "topic_names": ["Newsletter"], "updated_at": "2021-01-04T12:25:07Z", "updated_by": "user1", "version": 7, }, { ... } ]

GET /api2/mailing_recipients/:id — Fetch a mailing recipient email address

Mailing recipient email addresses exist implicitly. They do not need to be created first. A not previously created mailing recipient email address is active by default.

Response

The representation of the requested mailing recipient email address

Parameters:

Name	Description
`base_type`	base_type is always MailingRecipient Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	use the url-encoded recipient email address as ID Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing-recipient Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`active`	When sending mailings, this flag determines whether the WebCRM sends emails to this address. Type: `boolean`
`consent`	If the user has given their consent, the value is "given". If the user has revoked their consent, the value is "revoked". Otherwise the value is "unknown". Type: `string`
`topic_names`	A list of subscribed topic names. Type: `array`
`topic_names_unsubscribed`	A list of unsubscribed topic names. The unsubscribed topic names are computed as the difference set between all available topic names and the subscribed topic names. Type: `array`
`edit_reason`	A sentence that describes why the activeness/consent/subscriptions were changed, e.g. "recipient email address used the subscription form on www.foo.com". The text will be logged in the recipient email address. See `consent_logs`. Type: `string`
`consent_logs`	An array of log entries. Every entry is a hash with the keys `at`, `description` and `changes`. Type: `array`
`complained_at`	Type: `datetime`
`permanent_bounced_at`	Type: `datetime`
`consent_given_at`	Type: `datetime`
`consent_revoked_at`	Type: `datetime`

HTTP Response Code: 200

PUT /api2/mailing_recipients/:id — Updating or creating a mailing recipient email address

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name	Description
`active`	When sending mailings, this flag determines whether the WebCRM sends emails to this address. Type: `boolean`
`consent`	If the user has given their consent, the value is "given". If the user has revoked their consent, the value is "revoked". Otherwise the value is "unknown". Type: `string`
`topic_names`	A list of subscribed topic names. Type: `array`
`edit_reason`	A sentence that describes why the activeness/consent/subscriptions were changed, e.g. "recipient email address used the subscription form on www.foo.com". The text will be logged in the recipient email address. See `consent_logs`. Type: `string`

Response

The representation of the updated mailing recipient email address

Parameters:

Name	Description
`base_type`	base_type is always MailingRecipient Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	use the url-encoded recipient email address as ID Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always mailing-recipient Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`active`	When sending mailings, this flag determines whether the WebCRM sends emails to this address. Type: `boolean`
`consent`	If the user has given their consent, the value is "given". If the user has revoked their consent, the value is "revoked". Otherwise the value is "unknown". Type: `string`
`topic_names`	A list of subscribed topic names. Type: `array`
`topic_names_unsubscribed`	A list of unsubscribed topic names. The unsubscribed topic names are computed as the difference set between all available topic names and the subscribed topic names. Type: `array`
`edit_reason`	A sentence that describes why the activeness/consent/subscriptions were changed, e.g. "recipient email address used the subscription form on www.foo.com". The text will be logged in the recipient email address. See `consent_logs`. Type: `string`
`consent_logs`	An array of log entries. Every entry is a hash with the keys `at`, `description` and `changes`. Type: `array`
`complained_at`	Type: `datetime`
`permanent_bounced_at`	Type: `datetime`
`consent_given_at`	Type: `datetime`
`consent_revoked_at`	Type: `datetime`

HTTP Response Code: 200

TemplateSet

TemplateSet represents the singleton WebCRM template set

Attributes of TemplateSet

Name	Description
`base_type`	base_type is always TemplateSet. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`id`	id is always null Type: `string` Available for: `GET` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always template-set Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`templates`	The individual templates. When updating, missing entries are not deleted. Set them to `null` in order to delete them. Type: `object` Available for: `GET`, `POST`, `PUT`

GET /api2/template_set — Fetch the template set

Lists the current templates

Response

The representation of the template set

Parameters:

Name	Description
`base_type`	base_type is always TemplateSet. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	id is always null Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always template-set Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`templates`	The individual templates. When updating, missing entries are not deleted. Set them to `null` in order to delete them. Type: `object`

HTTP Response Code: 200

PUT /api2/template_set — Update the template set

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name Description

templates

The individual templates.

When updating, missing entries are not deleted. Set them to null in order to delete them.

Type: object

Requirements:

Templates have no Liquid syntax errors

Response

The representation of the updated template set

Parameters:

Name	Description
`base_type`	base_type is always TemplateSet. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	id is always null Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always template-set Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`templates`	The individual templates. When updating, missing entries are not deleted. Set them to `null` in order to delete them. Type: `object`

HTTP Response Code: 200

GET /api2/template_set/changes — Fetch the changelog of the template set

Request

Optional Parameters:

Name Description

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The template set changelog.

Lists the changed templates individually. The keys in the changes are formed like this: templates.$template_name.

Parameters:

Name Description

results

The changelog entries in reverse order (newer -> older)

Type: array

HTTP Response Code: 200

Example:

{ "results": [ { "changed_at": "2014-01-01T00:00:00Z", "changed_by": "root", "details": { "templates.digest_email_bcc": { "before": "foo@example.com", "after": "bar@example.com" }, } }, ] }

POST /api2/template_set/render_preview — Render a preview of the template set

Returns the templates after processing their Liquid code. Uses the context items as contexts for rendering.

A template for support cases, for example, might refer to an activity, a contact and perhaps other items to render. The template designer would thus pick one activity (a support case) and one contact from the already existing items and pass them to the render_preview action. The action would load these items into liquid drop and pass them to the liquid renderer. If a template accesses a liquid drop not present as a context, nothing is rendered instead of raising an error.

Request

Optional Parameters:

Name Description

templates

The templates can be a subset of the stored templates. They will be merged with the templates of the template set.

Type: object

context

Templates have access to these parameters.

The account, contact, activity, mailing and event keys expect an ID as input, will be loaded and are accessible to the templates. E.g. {"account": "23"} allows access to account.name of the account with the ID 23.

Type: object

Example:

{ "language": "en", "account": "23", "contact": "42" }

Requirements:

All IDs in context exist
Templates have no liquid syntax errors

Response

The preview of all templates. Returns a hash containing the rendered output of all templates.

HTTP Response Code: 200

Type

Type represents the WebCRM type model

Attributes of Type

Name	Description
`base_type`	base_type is always Type. Type: `string` Available for: `GET` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of the defined type, e.g. "support-case". Format: `/\A[A-Za-z][A-Za-z0-9-]*\Z/`, max 20 chars. Type: `string` Available for: `GET`, `POST` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always type Type: `string` Available for: `GET` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Available for: `GET` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Available for: `GET` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Available for: `GET` Example: `17`
`detail_info_template`	Liquid template that renders an item of this type in the list view Type: `string` Available for: `GET`, `POST`, `PUT`
`item_base_type`	The base type of the items based on this type. Possible base types: `Activity`, `Event`, `Mailing` `Contact`, `Account`, (singleton, builtin, r/w) `Collection`, `Type`, `EventContact`, `TemplateSet` (singleton, builtin, r/o) Type: `string` Available for: `GET`, `POST`
`icon_css_class`	Icon of the type definition, with semantic naming scheme: `$background-$foreground-$color` e.g. `folder-phone-red`, `book-clock-yellow`. Only supported for activities. Available backgrounds: `folder`, `book` Available foregrounds: `plain`, `phone`, `letter`, `globe`, `briefcase`, `clock`, `speechbubble` Available colors: `gray` (`#666666`), `red` (`#AA4040`), `green` (`#658B51`), `yellow` (`#C59F1D`), `blue` (`#305984`), `darkblue` (`#414E6A`) Type: `string` Available for: `GET`, `POST`, `PUT`
`languages`	A list of possible languages a contact can choose from, mainly used for communication with the contact, e.g. mailings. Only supported for contacts. Type: `array` Default: `["de", "en"]` Available for: `GET`, `POST`, `PUT`
`states`	The list of available activity states. Only supported for activities. Type: `array` Available for: `GET`, `POST`, `PUT` Example: `["open", "closed"]`
`attribute_definitions`	A hash of custom attribute definitions. The keys are the attribute names, the values are the respective attribute definitions. Limit 200. Attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Attribute types of custom attributes: `enum`, `multienum`, `string`, `text` Every definition has the following properties: `title` (`string`) `create` (`boolean`, whether the attribute can be set on create) `update` (`boolean`, whether the attribute can be changed on update) `read` (`boolean`, whether the api returns this attribute) `attribute_type` (`string`) Enums and multienums also have: `valid_values` (`array` of `strings`) Type: `object` Available for: `GET`, `POST`, `PUT` Example: `{ "custom_foo": { "title": "Foo", "attribute_type": "string", "mandatory": false, "max_length": 10, }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Available for: `GET`, `POST`, `PUT` Example: `["custom_foo", "custom_bar"]`
`standard_attribute_definitions`	A hash of internal attributes that are specific to this base type. Attribute types of standard attributes: `boolean`, e.g. `want_phonecall` `datetime, e.g.`created_at` `enum` `hash`, e.g. `templates` `integer`, e.g. `version` `list`, e.g. `tags` `multienum` `string` `text` Type: `object` Available for: `GET` Example: `{ "account_ids": { "create": true, "mandatory": false, "read": true, "title": "Accounts", "update": true, }, "comment_attachments": { "create": true, "mandatory": false, "read": false, "title": "Attachments", "update": true, }, }`

GET /api2/types — Fetch all types

Returns a list of type definitions (including standard types such as mailing, collection, and type).

Response

The representation of all types. Returns an array of types.

HTTP Response Code: 200

GET /api2/types/:id — Fetch a type

Returns the type definition. Also includes the definitions of the standard attributes.

Response

The representation of the requested type

Parameters:

Name	Description
`base_type`	base_type is always Type. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of the defined type, e.g. "support-case". Format: `/\A[A-Za-z][A-Za-z0-9-]*\Z/`, max 20 chars. Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always type Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`detail_info_template`	Liquid template that renders an item of this type in the list view Type: `string`
`item_base_type`	The base type of the items based on this type. Possible base types: `Activity`, `Event`, `Mailing` `Contact`, `Account`, (singleton, builtin, r/w) `Collection`, `Type`, `EventContact`, `TemplateSet` (singleton, builtin, r/o) Type: `string`
`icon_css_class`	Icon of the type definition, with semantic naming scheme: `$background-$foreground-$color` e.g. `folder-phone-red`, `book-clock-yellow`. Only supported for activities. Available backgrounds: `folder`, `book` Available foregrounds: `plain`, `phone`, `letter`, `globe`, `briefcase`, `clock`, `speechbubble` Available colors: `gray` (`#666666`), `red` (`#AA4040`), `green` (`#658B51`), `yellow` (`#C59F1D`), `blue` (`#305984`), `darkblue` (`#414E6A`) Type: `string`
`languages`	A list of possible languages a contact can choose from, mainly used for communication with the contact, e.g. mailings. Only supported for contacts. Type: `array` Default: `["de", "en"]`
`states`	The list of available activity states. Only supported for activities. Type: `array` Example: `["open", "closed"]`
`attribute_definitions`	A hash of custom attribute definitions. The keys are the attribute names, the values are the respective attribute definitions. Limit 200. Attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Attribute types of custom attributes: `enum`, `multienum`, `string`, `text` Every definition has the following properties: `title` (`string`) `create` (`boolean`, whether the attribute can be set on create) `update` (`boolean`, whether the attribute can be changed on update) `read` (`boolean`, whether the api returns this attribute) `attribute_type` (`string`) Enums and multienums also have: `valid_values` (`array` of `strings`) Type: `object` Example: `{ "custom_foo": { "title": "Foo", "attribute_type": "string", "mandatory": false, "max_length": 10, }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`
`standard_attribute_definitions`	A hash of internal attributes that are specific to this base type. Attribute types of standard attributes: `boolean`, e.g. `want_phonecall` `datetime, e.g.`created_at` `enum` `hash`, e.g. `templates` `integer`, e.g. `version` `list`, e.g. `tags` `multienum` `string` `text` Type: `object` Example: `{ "account_ids": { "create": true, "mandatory": false, "read": true, "title": "Accounts", "update": true, }, "comment_attachments": { "create": true, "mandatory": false, "read": false, "title": "Attachments", "update": true, }, }`

HTTP Response Code: 200

Example:

{ "attributes": { "version": { "title": "Version", "attribute_type": "integer", "read_only": true, }, "first_name": { "title": "First name", "attribute_type": "string", "read_only": true, }, "account_id": { "title": "Account", "attribute_type": "reference", "read_only": true, }, "custom_segment": { "title": "Segment", "attribute_type": "enum", "mandatory": false, "values": ["Großhändler", "Einzelhändler", "Lieferant", "Presse"] }, ... }, "base_type": "Type", "icon_css_class": null, "id": "contact", "item_base_type": "Contact", "type_id": "type", "version": 1, }

POST /api2/types — Create a type

Defines a new type. The attributes specified in attributes will be merged with the standard attributes.

There is a limit of max. 100 types. Deleted types count, too.

Request

Required Parameters:

Name Description

id

The ID of the defined type, e.g. "support-case".

Format: /\A[A-Za-z][A-Za-z0-9-]*\Z/, max 20 chars.

Type: string

Example:

"6013953fc6f360012d69d513d60cafd6"

item_base_type

The base type of the items based on this type.

Possible base types:

Activity, Event, Mailing
Contact, Account, (singleton, builtin, r/w)
Collection, Type, EventContact, TemplateSet (singleton, builtin, r/o)

Type: string

Optional Parameters:

Name	Description
`detail_info_template`	Liquid template that renders an item of this type in the list view Type: `string`
`icon_css_class`	Icon of the type definition, with semantic naming scheme: `$background-$foreground-$color` e.g. `folder-phone-red`, `book-clock-yellow`. Only supported for activities. Available backgrounds: `folder`, `book` Available foregrounds: `plain`, `phone`, `letter`, `globe`, `briefcase`, `clock`, `speechbubble` Available colors: `gray` (`#666666`), `red` (`#AA4040`), `green` (`#658B51`), `yellow` (`#C59F1D`), `blue` (`#305984`), `darkblue` (`#414E6A`) Type: `string`
`languages`	A list of possible languages a contact can choose from, mainly used for communication with the contact, e.g. mailings. Only supported for contacts. Type: `array` Default: `["de", "en"]`
`states`	The list of available activity states. Only supported for activities. Type: `array` Example: `["open", "closed"]`
`attribute_definitions`	A hash of custom attribute definitions. The keys are the attribute names, the values are the respective attribute definitions. Limit 200. Attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Attribute types of custom attributes: `enum`, `multienum`, `string`, `text` Every definition has the following properties: `title` (`string`) `create` (`boolean`, whether the attribute can be set on create) `update` (`boolean`, whether the attribute can be changed on update) `read` (`boolean`, whether the api returns this attribute) `attribute_type` (`string`) Enums and multienums also have: `valid_values` (`array` of `strings`) Type: `object` Example: `{ "custom_foo": { "title": "Foo", "attribute_type": "string", "mandatory": false, "max_length": 10, }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`

Response

The representation of the created type

Parameters:

Name	Description
`base_type`	base_type is always Type. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of the defined type, e.g. "support-case". Format: `/\A[A-Za-z][A-Za-z0-9-]*\Z/`, max 20 chars. Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always type Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`detail_info_template`	Liquid template that renders an item of this type in the list view Type: `string`
`item_base_type`	The base type of the items based on this type. Possible base types: `Activity`, `Event`, `Mailing` `Contact`, `Account`, (singleton, builtin, r/w) `Collection`, `Type`, `EventContact`, `TemplateSet` (singleton, builtin, r/o) Type: `string`
`icon_css_class`	Icon of the type definition, with semantic naming scheme: `$background-$foreground-$color` e.g. `folder-phone-red`, `book-clock-yellow`. Only supported for activities. Available backgrounds: `folder`, `book` Available foregrounds: `plain`, `phone`, `letter`, `globe`, `briefcase`, `clock`, `speechbubble` Available colors: `gray` (`#666666`), `red` (`#AA4040`), `green` (`#658B51`), `yellow` (`#C59F1D`), `blue` (`#305984`), `darkblue` (`#414E6A`) Type: `string`
`languages`	A list of possible languages a contact can choose from, mainly used for communication with the contact, e.g. mailings. Only supported for contacts. Type: `array` Default: `["de", "en"]`
`states`	The list of available activity states. Only supported for activities. Type: `array` Example: `["open", "closed"]`
`attribute_definitions`	A hash of custom attribute definitions. The keys are the attribute names, the values are the respective attribute definitions. Limit 200. Attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Attribute types of custom attributes: `enum`, `multienum`, `string`, `text` Every definition has the following properties: `title` (`string`) `create` (`boolean`, whether the attribute can be set on create) `update` (`boolean`, whether the attribute can be changed on update) `read` (`boolean`, whether the api returns this attribute) `attribute_type` (`string`) Enums and multienums also have: `valid_values` (`array` of `strings`) Type: `object` Example: `{ "custom_foo": { "title": "Foo", "attribute_type": "string", "mandatory": false, "max_length": 10, }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`
`standard_attribute_definitions`	A hash of internal attributes that are specific to this base type. Attribute types of standard attributes: `boolean`, e.g. `want_phonecall` `datetime, e.g.`created_at` `enum` `hash`, e.g. `templates` `integer`, e.g. `version` `list`, e.g. `tags` `multienum` `string` `text` Type: `object` Example: `{ "account_ids": { "create": true, "mandatory": false, "read": true, "title": "Accounts", "update": true, }, "comment_attachments": { "create": true, "mandatory": false, "read": false, "title": "Attachments", "update": true, }, }`

HTTP Response Code: 201

PUT /api2/types/:id — Update a type

For optimistic locking, send the current version in an If-Match HTTP header.

Request

Optional Parameters:

Name	Description
`detail_info_template`	Liquid template that renders an item of this type in the list view Type: `string`
`icon_css_class`	Icon of the type definition, with semantic naming scheme: `$background-$foreground-$color` e.g. `folder-phone-red`, `book-clock-yellow`. Only supported for activities. Available backgrounds: `folder`, `book` Available foregrounds: `plain`, `phone`, `letter`, `globe`, `briefcase`, `clock`, `speechbubble` Available colors: `gray` (`#666666`), `red` (`#AA4040`), `green` (`#658B51`), `yellow` (`#C59F1D`), `blue` (`#305984`), `darkblue` (`#414E6A`) Type: `string`
`languages`	A list of possible languages a contact can choose from, mainly used for communication with the contact, e.g. mailings. Only supported for contacts. Type: `array` Default: `["de", "en"]`
`states`	The list of available activity states. Only supported for activities. Type: `array` Example: `["open", "closed"]`
`attribute_definitions`	A hash of custom attribute definitions. The keys are the attribute names, the values are the respective attribute definitions. Limit 200. Attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Attribute types of custom attributes: `enum`, `multienum`, `string`, `text` Every definition has the following properties: `title` (`string`) `create` (`boolean`, whether the attribute can be set on create) `update` (`boolean`, whether the attribute can be changed on update) `read` (`boolean`, whether the api returns this attribute) `attribute_type` (`string`) Enums and multienums also have: `valid_values` (`array` of `strings`) Type: `object` Example: `{ "custom_foo": { "title": "Foo", "attribute_type": "string", "mandatory": false, "max_length": 10, }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`

Response

The representation of the updated type

Parameters:

Name	Description
`base_type`	base_type is always Type. Type: `string` Example: `"Account"`
`changed_at`	The timestamp of the last change made to the item, independently of the originator. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`created_at`	The timestamp of the creation of the item Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`id`	The ID of the defined type, e.g. "support-case". Format: `/\A[A-Za-z][A-Za-z0-9-]*\Z/`, max 20 chars. Type: `string` Example: `"6013953fc6f360012d69d513d60cafd6"`
`type_id`	type_id is always type Type: `string` Example: `"support-case"`
`updated_at`	The timestamp of the last change made to the item, always requires a user to do the update. May be `null`. Type: `datetime` Example: `"2014-01-01T00:00:00Z"`
`updated_by`	The login of the user who updated the item at `updated_at`. May be the empty string. Type: `string` Example: `"root"`
`version`	The version number of the change. It is incremented on every change. Type: `integer` Example: `17`
`detail_info_template`	Liquid template that renders an item of this type in the list view Type: `string`
`item_base_type`	The base type of the items based on this type. Possible base types: `Activity`, `Event`, `Mailing` `Contact`, `Account`, (singleton, builtin, r/w) `Collection`, `Type`, `EventContact`, `TemplateSet` (singleton, builtin, r/o) Type: `string`
`icon_css_class`	Icon of the type definition, with semantic naming scheme: `$background-$foreground-$color` e.g. `folder-phone-red`, `book-clock-yellow`. Only supported for activities. Available backgrounds: `folder`, `book` Available foregrounds: `plain`, `phone`, `letter`, `globe`, `briefcase`, `clock`, `speechbubble` Available colors: `gray` (`#666666`), `red` (`#AA4040`), `green` (`#658B51`), `yellow` (`#C59F1D`), `blue` (`#305984`), `darkblue` (`#414E6A`) Type: `string`
`languages`	A list of possible languages a contact can choose from, mainly used for communication with the contact, e.g. mailings. Only supported for contacts. Type: `array` Default: `["de", "en"]`
`states`	The list of available activity states. Only supported for activities. Type: `array` Example: `["open", "closed"]`
`attribute_definitions`	A hash of custom attribute definitions. The keys are the attribute names, the values are the respective attribute definitions. Limit 200. Attribute names must be prefixed with `custom_`. When updating, attributes not specified are not deleted. Set them to `null` in order to delete them. Attribute types of custom attributes: `enum`, `multienum`, `string`, `text` Every definition has the following properties: `title` (`string`) `create` (`boolean`, whether the attribute can be set on create) `update` (`boolean`, whether the attribute can be changed on update) `read` (`boolean`, whether the api returns this attribute) `attribute_type` (`string`) Enums and multienums also have: `valid_values` (`array` of `strings`) Type: `object` Example: `{ "custom_foo": { "title": "Foo", "attribute_type": "string", "mandatory": false, "max_length": 10, }, ... }`
`attribute_order`	The attribute names in the order to be used in a GUI. Attribute names must be prefixed with `custom_`. Attributes not specified are sorted in last. Type: `array` Example: `["custom_foo", "custom_bar"]`
`standard_attribute_definitions`	A hash of internal attributes that are specific to this base type. Attribute types of standard attributes: `boolean`, e.g. `want_phonecall` `datetime, e.g.`created_at` `enum` `hash`, e.g. `templates` `integer`, e.g. `version` `list`, e.g. `tags` `multienum` `string` `text` Type: `object` Example: `{ "account_ids": { "create": true, "mandatory": false, "read": true, "title": "Accounts", "update": true, }, "comment_attachments": { "create": true, "mandatory": false, "read": false, "title": "Attachments", "update": true, }, }`

HTTP Response Code: 200

DELETE /api2/types/:id — Delete a type

For optimistic locking, send the current version in an If-Match HTTP header.

Response

HTTP Response Code: 200

GET /api2/types/:id/changes — Fetch the changelog of a type

Request

Optional Parameters:

Name Description

limit

The number of changelog entries to fetch at most. The max. limit is 100.

Type: integer

Default: 10

Response

The types changelog.

Lists the changed attributes individually. The keys in the changes are formed like this: attributes.$attribute_name.

Parameters:

Name Description

results

The changelog entries in reverse order (newer -> older)

Type: array

HTTP Response Code: 200

REST API v2

WebCRM Web Services API ​version 2

Table of Contents

Preface

General Rules / Guidelines

Development with curl

Errors

unauthorized

Response

forbidden

Response

not_found

Response

conflict

Response

too_many_params

Response

authentication_failed

Response

sending_email_failed

Response

invalid_values

Response

invalid_keys

Response

item_state_precondition_failed

Response

params_parse_error

Response

rate_limit

Response

internal_server_error

Response

Global

GET /api2/mget — Fetch multiple items of any base type

Request

Response

POST /api2/search — Search items

Request

Response

Account

Attributes of Account

GET /api2/accounts/:id — Fetch an account

Response

POST /api2/accounts — Create an account

Request

Response

PUT /api2/accounts/:id — Update an account

Request

Response

DELETE /api2/accounts/:id — Delete an account

Response

POST /api2/accounts/:id/merge_and_delete — Merge and delete an account

Request

Response

GET /api2/accounts/:id/changes — Fetch the changelog of an account

Request

Response

Activity

Attributes of Activity

GET /api2/activities/:id — Fetch an activity

Response

POST /api2/activities — Create an activity

Request

Response

PUT /api2/activities/:id — Update an activity

Request

Response

DELETE /api2/activities/:id — Delete an activity

Response

GET /api2/activities/:id/changes — Fetch the changelog of an activity

Request

Response

AttachmentStore

POST /api2/attachment_store/generate_upload_permission — Generate an upload permission to upload a file directly to S3

Response

POST /api2/attachment_store/generate_download_url — Generate a download URL

Request

Response

Collection

WebCRM Web Services API version 2