fincrm Logo
API docs by Redocly

fincrm API (0.1.1)

Need help?: it@fincrm.de URL: https://fincrm.de/

Introduction

The fincrm is an http based restful json api. The api is currently in the alpha phase, so that third party developers can provide us with feedback before we will release the beta and stable version of the api. Although we try to avoid it, the API might change without further announcement during alpha phase.

If you have questions, comments or other feedback regarding the api dont hesitate to contact us.

Sign up to our developer newsletter to get notified about api changes.

Changelog

All notable changes to this project will be documented in this section.

[0.1.1] - 2023-10-20

  • Added POST /leads endpoint to create a case with one single request (applicants, purpose and property).
  • Added GET /customers/{customerId}/tags endpoint to get all tags of a customer.
  • Added POST /customers/{customerId}/tags endpoint to ass one or more tags to a customer.
  • Added DELETE /customers/{customerId}/tags endpoint to remove one or more tags from a customer.

[0.1.0] - 2023-04-20

  • Added GET /institutes/{institudeId} endpoint.
  • Added POST /institutes/ endpoint.
  • Added PUT /institutes/{institudeId} endpoint.
  • Added DELETE /institutes/{institudeId} endpoint.

[0.0.9] - 2023-04-12

  • Added GET /institutes endpoint.

[0.0.8] - 2023-03-03

  • Added GET /intermediaries endpoint.

[0.0.7] - 2022-09-08

  • Added GET /customers/{customerId}/purposes endpoint.
  • Added POST /customers/{customerId}/properties endpoint.
  • Changed the type of purpose.state from integer (-1, 0, 1,2) to string (ACTIVE, ON_HOLD, WON, LOST) and removed property state_name.
  • Replaced purpose properties won_at, lost_at, on_hold_since with state_since.
  • Replaced purpose properties loss_reason, on_hold_reason with state_reason.
  • Replaced purpose properties loss_note, on_hold_note with state_note.

[0.0.6] - 2022-08-23

  • Added fields to customer endpoints.
  • Added GET /customers/{customerId}/properties endpoint.
  • Added POST /customers/{customerId}/properties endpoint.
  • Removed salutation as required field from customer endpoints.
  • Allow 100 instead of 5 chars for all street_number fields.

[0.0.5] - 2020-01-17

  • Improved documentation for date and datetime fields (UTC).

[0.0.4] - 2019-11-07

  • Added documentation for the authentication endpoints.

[0.0.3] - 2019-06-07

  • BREAKING CHANGE Changed the request validation rules for POST */customers and PUT */customers endpoints.
  • Previous validation for contact information: Required email or email_offices.
  • Current validation for contact information: One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile

[0.0.2] - 2019-04-12

  • BREAKING CHANGE Changed the oauth authorization url from https://{subdomain}.fincrm.de/api/v1/oauth/authorize to https://{subdomain}.fincrm.de/oauth/authorize.
  • Added GET /customers/{customerId}/notes endpoint.
  • Added POST /customers/{customerId}/notes endpoint.
  • Added GET /customers/{customerId}/notes/{noteId} endpoint.
  • Added PUT /customers/{customerId}/notes/{noteId} endpoint.
  • Added DELETE /customers/{customerId}/notes/{noteId} endpoint.
  • Added GET /industries endpoint.
  • Added documentation for nested relations of customers.
  • Improved the documentation for filter operators of the GET /customers endpoint.
  • Added documentation for the fields query parameter of the GET /customers endpoint.
  • Added documentation for required Headers (Accept Header).

[0.0.1] - 2019-03-31

  • Initial Release

Authentication

fincrm API supports two authentication methods: OAuth 2 (Authorization Code Grant) and Personal Access Tokens.

OAuth2

This is the preferred authentication method for the fincrm Api.

When using authorization codes, a client application will redirect a user to the fincrm server where they will either approve or deny the authorization request to issue an access token to the client.

fincrm issues access tokens that expire after one year.

First the 3rd party application (the client) needs to be registered in the finCRM application settings with a name and a URL that finCRM can redirect to after users approve the request for authorization. Once a client has been created, developers may use the client ID and secret to request an authorization code and access token from fincrm.

Requesting Tokens

After registering the application (client) the client should make a redirect request to fincrm´s https://{subdomain}.fincrm.de/oauth/authorize endpoint:

  • client_id: [CLIENT_ID] (defined when the client was registered)
  • redirect_uri: [REDIRECT_URI] (defined when the client was registered)
  • response_type: 'code'
  • scope: ''
  • state: [CLIENT_STATE] (Optional, an opaque value used by the client to maintain state between the request and callback)

When receiving the authorization request, fincrm will ask the user to approve or deny the request. If the user approves the authorization request, they will be redirected back to the consuming application.

Converting Authorization Codes To Access Tokens

The consuming application should then issue a POST request to fincrms https://{subdomain}.fincrm.de/api/v1/oauth/token endpoint to request an access token:

  • grant_type: 'authorization_code'
  • client_id: [CLIENT_ID] (defined when the client was registered)
  • client_secret: [CLIENT_SECRET] (defined when the client was registered)
  • redirect_uri: [REDIRECT_URI] (defined when the client was registered)
  • code: [AUTHORIZATION_CODE] (authorization code that was issued by fincrm when the user approved the authorization request)

fincrm will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.

Refreshing Tokens

Users will need to refresh their access tokens after 1 year via the refresh token that was provided to them when the access token was issued. Consuming applications can refresh the access token by sending a POST request to the https://{subdomain}.fincrm.de/api/v1/oauth/token endpoint:

  • grant_type: 'refresh_token'
  • refresh_token: [REFRESH_TOKEN] (provided when the access token was issued)
  • client_id: [CLIENT_ID] (defined when the client was registered)
  • client_secret: [CLIENT_SECRET] (defined when the client was registered)
  • scope: ''

fincrm will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.

Using access tokens to access fincrm API

3rd Party applications should send the access token as a Bearer token in the Authorization header of their request.

Security Scheme Type: OAuth2
Flow type: authorizationCode
Authorization URL: https://{subdomain}.fincrm.de/oauth/authorize
Token URL: https://{subdomain}.fincrm.de/api/v1/oauth/token
Scopes:
  • * -

    fincrm API currently does not support scoped tokens.

PersonalAccessToken

fincrm users are able to issue access tokens to themselves in the settings area of the fincrm application without going through the typical authorization code redirect flow. This is helpful for testing and development purposes.

Personal access tokens are always long-lived tokens and will not expire. Use it with caution!

Using access tokens to access fincrm API

3rd Party applications should send the access token as a Bearer token in the Authorization header of their request.

Security Scheme Type: HTTP
HTTP Authorization Scheme: Bearer

Filter

Operators can optionally be used to filter finCRM resources.

Usage: api/[VERSION]/[ENDPOINT]/?[FIELD]:[OPERATOR]=[VALUE]

The allowed operators depend on the field.

Available Operators

  • lte: The field should be less than or equal to the given value. [FIELD]:lte=5
  • gte: The field should be greater than or equal to the given value. [FIELD]:gte=5
  • lt: The field should be less than the given value. [FIELD]:lt=5
  • gt: The field should be greater than the given value. [FIELD]:gt=5
  • like: The field should contain the given value. Wildcards are allowed in the value. [FIELD]:like=*my-query*
  • not-like: The field should not contain the given value. Wildcards are allowed in the value. [FIELD]:not-like=*my-query*
  • in: The field should be equal to any of the values separated by comma. [FIELD]:in=1,2,3
  • not-in: The field should not be equal to any of the values separated by comma. [FIELD]:not-in=1,2,3
  • bt: The field should not be between two values separated by comma. [FIELD]:bt=2018-01-01,2018-12-12

Throttling

fincrm API has a rate limit of 60 requests per minute. If you exceed this limit, you will get a 429 Too Many Requests response for subsequent requests.

Response Headers

  • X-RateLimit-Limit: The maximum number of requests that the consumer is permitted to make per minute.
  • X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
  • X-RateLimit-Reset: The time at which the current rate limit window resets in UTC epoch seconds.

Leads

All Endpoints related to the Leads

Create a lead

Create a new lead with the applicants (customer & partner), property and purpose.

Authorizations:
OAuth2PersonalAccessToken
header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/json
required
Array of objects (Applicant) [ 1 .. 2 ] items

An array containing the applicants of the lead..

required
object (LeadPurpose)

The purpose of the lead

(string or null) or (integer or null)

The email address or id of the user the lead should be assigned to. If no email or id is provided or the user could not be found, the lead will be assigned by the system.

CUSTOMER (object) or INTERMEDIARY (object) or CUSTOM (object)
object or null (LeadProperty)

The property of the lead

notes
Array of strings or null
Default: "[]"

An array containing the notes for the applicant 1.

notify
boolean or null
Default: false

Whether or not the owner of the lead should be notified.

tags
Array of strings or null
Default: "[]"

An array containing the name of tags of the lead. The tags are case insensitive.

Responses

Request samples

Content type
application/json
{
  • "assign_to": "test@fincrm.de",
  • "source": {
    • "type": "CUSTOMER",
    • "id": 24,
    • "email": "test@fincrm.de"
    },
  • "applicants": [
    • {
      }
    ],
  • "property": {
    • "type": "APARTMENT",
    • "usage": "MIXED_USE",
    • "construction_year": 2018,
    • "postal_code": "50273",
    • "city": "Köln",
    • "federal_state": "NRW",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "living_area": 120,
    • "property_size": 500
    },
  • "purpose": {
    • "type": "BUILDING_LOAN_CONTRACT",
    • "capital_requirements": {
      },
    • "capital_invested": {
      }
    },
  • "notes": [
    • "This is my new note.",
    • "This is my second note."
    ],
  • "notify": true,
  • "tags": [
    • "Muster Tag",
    • "Muster Tag 2"
    ]
}

Response samples

Content type
application/json
{
  • "applicants": [
    • {
      }
    ],
  • "property": {
    • "id": 24,
    • "type": "APARTMENT",
    • "usage": "MIXED_USE",
    • "construction_year": 2018,
    • "postal_code": "50273",
    • "city": "Köln",
    • "federal_state": "NRW",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "living_area": 120,
    • "property_size": 500
    },
  • "purpose": {
    • "id": 24,
    • "type": "BUILDING_LOAN_CONTRACT",
    • "capital_requirements": {
      },
    • "capital_invested": {
      }
    }
}

Customers

All Endpoints related to the customer entity.

List customers.

Returns a list of customers matching the filter criterias.

Authorizations:
OAuth2PersonalAccessToken
query Parameters
advisor
string
Example: advisor=2#user

'Filter the results by advisor of the customer. The value consists of the advisor_id followed by # as separator and the advisor_type.'

birthday_period
string
Enum: "current_month" "current_week" "last_3_month" "last_6_month" "last_month" … 8 more
Example: birthday_period=next_week

Filter the results by a birthday period. Show only customers that birthday is in the given period.

channel_id
integer
Example: channel_id=12

Filter the results by channel_id of the customer

city
string
Example: city=Musterstadt

'Filter the results by city of the customer. Allowed operators: like.'

company
string
Example: company=Muster GmbH

'Filter the results by company of the customer. Allowed operators: like.'

created_by
integer
Example: created_by=14

Filter the results by the id of the creator (user) of the customer

created_at_end
string <date>
Example: created_at_end=2019-01-25

Filter the results by created_at end date.

created_at_period
string
Enum: "current_month" "current_week" "current_year" "last_month" "last_week" … 3 more
Example: created_at_period=current_year

Filter the results by a created_at period.

created_at_start
string <date>
Example: created_at_start=2019-01-25

Filter the results by created_at start date.

do_not_disturb
integer
Enum: 0 1
Example: do_not_disturb=1

Filter the results by the do not disturb filter.

first_name
string
Example: first_name=max

Filter the results by first name of the customer.

last_name
string
Example: last_name=mustermann

Filter the results by last name of the customer.

email
string
Example: email=max.mustermann@musterweb.de

'Filter the results by email of the customer. Allowed operators: like.'

fields
Array of arrays
Items Enum: "first_name" "id" "last_name"
Example: fields=id,first_name

Show only a subset of the customers field.

job
string
Example: job=Architekt

'Filter the results by job of the customer. Allowed operators: like.'

no_channel
integer
Enum: 0 1
Example: no_channel=1

Filter the results by the empty channel of the customer.

occupational_group_id
number
Example: occupational_group_id=1

Filter the results by last occupational group of the customer.

owner_id
integer
Example: owner_id=12

Filter the results by the id of the owner (user) of the customer. Allowed operators: in.

page
integer >= 1
Default: 1
Example: page=3

The page to show.

per_page
integer >= 1
Default: 15
Example: per_page=25

The number of customers showed on each page.

phone
string
Example: phone=2834653878

'Filter the results by phone_private, phone_office and mobile of the customer. Allowed operators: like.'

postal_code
string
Example: postal_code=50362

'Filter the results by postal_code of the customer. Allowed operators: like.'

q
string
Example: q=Max Mustermann

Search the items by simple text search.

salutation
Array of any
Items Enum: 1 2
Example: salutation=1

'Filter the results by salutation/gender of the customer. Allowed operators: in.'

sort
string
Enum: "address" "advisor_id" "birthday" "company" "created_at" … 16 more
Example: sort=-updated_at

Sort customers by a field. Prepend - to a field to sort in descending order.

sourceable
string
Example: sourceable=2#intermediary

'Filter the results by sourceable of the customer. The value consists of the sourceable_id followed by # as separator and the sourceable_type.'

street
string
Example: street=Musterstraße

'Filter the results by street of the customer. Allowed operators: like.'

tags
integer
Example: tags=2

Filter the results by tags of the customer

updated_at_end
string <date>
Example: updated_at_end=2019-01-25

Filter the results by updated_at end date.

updated_at
string <date>
Example: updated_at=2018-09-23T12:13:42

Filter the results by a updated_at.

updated_at_period
string
Enum: "current_month" "current_week" "current_year" "last_month" "last_week" … 3 more
Example: updated_at_period=current_year

Filter the results by a updated_at period.

updated_at_start
string <date>
Example: updated_at_start=2019-01-25

Filter the results by updated_at start date.

with
Array of arrays
Items Enum: "advisor" "channel" "creator" "owner" "partners" … 2 more
Example: with=owner,partners

Load nested resources. Multiple values separated by comma are allowed.

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 2675,
    • "owner_id": 28,
    • "advisor_id": 12,
    • "advisor_type": "intermediary",
    • "channel_id": 3,
    • "sourceable_id": 12,
    • "sourceable_type": "intermediary",
    • "salutation": "Herr",
    • "title": "Dr.",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "email_office": "max-mustermann@muster-gmbh.de",
    • "birthday": "1985-09-15",
    • "birth_place": "Musterstadt",
    • "birth_name": "Mustermännchen",
    • "phone_private": "+49 231-23752122",
    • "phone_office": "+49 231-27519062",
    • "mobile": "+49 171-242233212",
    • "fax": "+49 231-324553332",
    • "do_not_disturb": false,
    • "homepage": "https://www.fincrm.de",
    • "industry_id": 3,
    • "company": "Mustermann GmbH",
    • "employment_state": "permanent",
    • "employer_in_germany": true,
    • "job": "Online Redakteur",
    • "employed_since": "2014-01-01",
    • "employment_temporary_until": "2030-01-01",
    • "occupational_group_id": 1,
    • "retires_at": "2038-01-01",
    • "nationality": "DE",
    • "marital_status": "Verheiratet",
    • "marital_property": "Gesetzlicher Güterstand",
    • "identity_card": "A2973NBUG2232",
    • "identity_card_created_at": "2015-23-01",
    • "identity_card_created_by": "Stadt Köln",
    • "identity_card_expires_at": "2035-22-01",
    • "country": "DE",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "previous_address": {
      },
    • "resident_since": "1995-04-01",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_id": "633876272618",
    • "external_id": "user-123XX",
    • "full_name_reversed": "Mustermann, Max",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34,
    • "advisor": {
      },
    • "channel": {
      },
    • "creator": {
      },
    • "editor": {
      },
    • "owner": {
      },
    • "partners": [
      ],
    • "sourceable": {
      },
    • "tags": [
      ],
    • "abilities": {
      }
    }
]

Create customer.

Create a new customer.

Authorizations:
OAuth2PersonalAccessToken
header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/x-www-form-urlencoded
One of
email
required
string <email> [ 1 .. 255 ]
Default: null

The customers email address. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

first_name
required
string [ 1 .. 255 ]
Default: ""

The customers first name.

last_name
required
string [ 1 .. 255 ]
Default: null

The customers last name

owner_id
integer
Default: null

The id of the owner of the customer

advisor_id
integer
Default: null

The id of the adviser

advisor_type
string
Default: null
Enum: "intermediary" "user"

The type of the advisor

channel_id
integer
Default: null

The id of the source channel

sourceable_id
integer
Default: null

The id of the adviser

sourceable_type
string
Default: null
Enum: "customer" "intermediary" "source"

The type of the source.

salutation
string
Default: ""
Enum: "Frau" "Herr"

The customers salutation.

title
string
Default: null
Enum: "Dr." "Prof." "Prof. Dr."

The customers title.

email_office
string <email> [ 1 .. 255 ]
Default: null

The customers office email address. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

birthday
string <date>
Default: null

The birthday of the customer.

birth_place
string [ 1 .. 255 ]
Default: null

The customers birth place.

birth_name
string [ 1 .. 255 ]
Default: null

The customers birth name.

phone_private
string [ 1 .. 255 ]
Default: null

The customers primary private phone number. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

phone_office
string [ 1 .. 255 ]
Default: null

The customers primary office phone number. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

mobile
string [ 1 .. 255 ]
Default: null

The customers primary mobile phone number. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

fax
string [ 1 .. 255 ]
Default: null

The customers primary fax number.

do_not_disturb
boolean
Default: false

Whether or not the customer wants to be contacted.

homepage
string [ 1 .. 255 ]
Default: null

Whether or not the customer wants to be contacted.

industry_id
number
Default: null
Enum: 1 10 11 12 13 … 34 more

The industry values are:

  • 1 = Architektur & Bauwesen
  • 2 = Automobilindustrie
  • 3 = Baugewerbe
  • 4 = Beratung/Consulting
  • 5 = Bildungswesen
  • 6 = Coaching
  • 7 = Computer Software
  • 8 = Design
  • 9 = Dienstleistungen
  • 10 = Druck
  • 11 = Einzelhandel
  • 12 = Elektrotechnik
  • 13 = Erneuerbare Energiequellen & Umwelt
  • 14 = Finanzdienstleistungen
  • 15 = Fotografie
  • 16 = Freizeit & Tourismus
  • 17 = Gesundheit & Fitness
  • 18 = Gesundheitswesen
  • 19 = Großhandel
  • 20 = Hotel & Gaststätten
  • 21 = Immobilien
  • 22 = Informationstechnologie & -dienste
  • 23 = Internet
  • 24 = Lebensmittel
  • 25 = Logistik & Zulieferung
  • 26 = Marketing & Werbung
  • 27 = Maschinenbau & Betriebstechnik
  • 28 = Medienproduktion
  • 29 = Metallindustrie/-verarbeitung
  • 30 = Öffentlichkeitsarbeit & Kommunikation
  • 31 = Personalbeschaffung
  • 32 = Personalwesen
  • 33 = Rechtsberatung
  • 34 = Sport
  • 35 = Steuerberatung/Wirtschaftsprüfung
  • 36 = Telekommunikation
  • 37 = Unternehmensberatung
  • 38 = Veranstaltungsdienstleistungen
  • 39 = Versicherungen
company
string [ 1 .. 255 ]
Default: null

The company the customer works for.

employment_state
string
Default: null
Enum: "permanent" "temporary"

The customers employment state.

employer_in_germany
boolean
Default: null

Whether or not the employer is situated in germany.

job
string [ 1 .. 255 ]
Default: null

The customers job.

employed_since
string <date>
Default: null

The date since the customer works in his current job.

employment_temporary_until
string <date>
Default: null

The date until the customer works in his temporary job.

occupational_group_id
number
Default: null
Enum: 1 10 2 3 4 … 5 more

The occupational group values are:

  • 1 = Angestelle(r)
  • 2 = Leitende(r) Angestellte(r)
  • 3 = Arbeiter(in)
  • 4 = Beamte(r)
  • 5 = Rentner(in)
  • 6 = Hausfrau-/Mann
  • 7 = Selbstständig
  • 8 = Freiberufler(in)
  • 9 = Arbeitslos
  • 10 = Sonstiges
retires_at
string <date>
Default: null

The date when the customer will retire.

nationality
string
Default: null
Enum: "AD" "AE" "AF" "AG" "AL" … 183 more

The nationality.

marital_status
string
Default: null
Enum: "Geschieden" "Getrennt lebend" "Ledig" "Verheiratet" "Verpartnert" … 1 more

The marital status of the customer.

marital_property
string
Default: null
Enum: "Gesetzlicher Güterstand" "Gütergemeinschaft" "Gütertrennung"

The marital property of the customer.

identity_card
string [ 1 .. 255 ]
Default: null

The identy card number of the customer.

identity_card_created_at
string <date>
Default: null

The date when identity card was created.

identity_card_created_by
string
Default: null

The authority that authorized the identity card.

identity_card_expires_at
string <date>
Default: null

The date when identity card expires.

country
string [ 2 .. 2 ]
Default: null

The country the customer lives in (ISO-3166 Alpha 2 code i.e. "DE").

city
string [ 1 .. 255 ]
Default: null

The city the customer lives in.

street
string [ 1 .. 255 ]
Default: null

The street the customer lives in.

street_number
string [ 1 .. 100 ]
Default: null

The street number of the customer.

postal_code
string [ 3 .. 12 ]
Default: null

The customers postal code (zip).

object
Default: {}

The customer's old address.

resident_since
string <date>
Default: null

The date since the customer staying in the current residence.

bank_account
string [ 2 .. 70 ]
Default: null

The customers bank account name.

bank_institution
string [ 2 .. 255 ]
Default: null

The customers bank name.

iban
string [ 22 .. 34 ]
Default: null

The customers iban.

bic
string [ 11 .. 22 ]
Default: null

The customers bic.

tax_id
string [ 11 .. 11 ]
Default: null

The customers tax id.

external_id
string
Default: null

An optional custom identifier.

created_at
string <date-time>
Default: null

The date when the customer was created (UTC).

Responses

Response samples

Content type
application/json
{
  • "id": 2675,
  • "owner_id": 28,
  • "advisor_id": 12,
  • "advisor_type": "intermediary",
  • "channel_id": 3,
  • "sourceable_id": 12,
  • "sourceable_type": "intermediary",
  • "salutation": "Herr",
  • "title": "Dr.",
  • "first_name": "Max",
  • "last_name": "Mustermann",
  • "email": "max-mustermann@mustermail.de",
  • "email_office": "max-mustermann@muster-gmbh.de",
  • "birthday": "1985-09-15",
  • "birth_place": "Musterstadt",
  • "birth_name": "Mustermännchen",
  • "phone_private": "+49 231-23752122",
  • "phone_office": "+49 231-27519062",
  • "mobile": "+49 171-242233212",
  • "fax": "+49 231-324553332",
  • "do_not_disturb": false,
  • "homepage": "https://www.fincrm.de",
  • "industry_id": 3,
  • "company": "Mustermann GmbH",
  • "employment_state": "permanent",
  • "employer_in_germany": true,
  • "job": "Online Redakteur",
  • "employed_since": "2014-01-01",
  • "employment_temporary_until": "2030-01-01",
  • "occupational_group_id": 1,
  • "retires_at": "2038-01-01",
  • "nationality": "DE",
  • "marital_status": "Verheiratet",
  • "marital_property": "Gesetzlicher Güterstand",
  • "identity_card": "A2973NBUG2232",
  • "identity_card_created_at": "2015-23-01",
  • "identity_card_created_by": "Stadt Köln",
  • "identity_card_expires_at": "2035-22-01",
  • "country": "DE",
  • "city": "Köln",
  • "street": "Musterstraße",
  • "street_number": "3a",
  • "postal_code": "50273",
  • "previous_address": {
    • "city": "Tunis",
    • "street": "Habib 5",
    • "street_number": "15",
    • "postal_code": "9100"
    },
  • "resident_since": "1995-04-01",
  • "bank_account": "Max Mustermann",
  • "bank_institution": "Musterbank Köln",
  • "iban": "DE12500105170648489890",
  • "bic": "DABAIE2D",
  • "tax_id": "633876272618",
  • "external_id": "user-123XX",
  • "full_name_reversed": "Mustermann, Max",
  • "created_at": "2018-09-15T15:28:23+00:00",
  • "updated_at": "2018-09-23T12:13:42+00:00",
  • "created_by": 2,
  • "updated_by": 34,
  • "advisor": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "channel": {
    • "id": 232,
    • "name": "Muster Tag",
    • "is_system": 0,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "creator": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "editor": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "owner": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "partners": [
    • {
      }
    ],
  • "sourceable": {
    • "id": 24,
    • "channel_id": 3,
    • "name": "Muster Quelle",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "tags": [
    • {
      }
    ],
  • "abilities": {
    • "can_edit": true,
    • "can_delete": false
    }
}

Show customer.

Get information about a customer by id.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer

query Parameters
with
Array of arrays
Items Enum: "advisor" "channel" "creator" "editor" "owner" … 4 more
Example: with=owner,tags,creator

Load nested resources. Multiple values separated by comma are allowed.

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
{
  • "id": 2675,
  • "owner_id": 28,
  • "advisor_id": 12,
  • "advisor_type": "intermediary",
  • "channel_id": 3,
  • "sourceable_id": 12,
  • "sourceable_type": "intermediary",
  • "salutation": "Herr",
  • "title": "Dr.",
  • "first_name": "Max",
  • "last_name": "Mustermann",
  • "email": "max-mustermann@mustermail.de",
  • "email_office": "max-mustermann@muster-gmbh.de",
  • "birthday": "1985-09-15",
  • "birth_place": "Musterstadt",
  • "birth_name": "Mustermännchen",
  • "phone_private": "+49 231-23752122",
  • "phone_office": "+49 231-27519062",
  • "mobile": "+49 171-242233212",
  • "fax": "+49 231-324553332",
  • "do_not_disturb": false,
  • "homepage": "https://www.fincrm.de",
  • "industry_id": 3,
  • "company": "Mustermann GmbH",
  • "employment_state": "permanent",
  • "employer_in_germany": true,
  • "job": "Online Redakteur",
  • "employed_since": "2014-01-01",
  • "employment_temporary_until": "2030-01-01",
  • "occupational_group_id": 1,
  • "retires_at": "2038-01-01",
  • "nationality": "DE",
  • "marital_status": "Verheiratet",
  • "marital_property": "Gesetzlicher Güterstand",
  • "identity_card": "A2973NBUG2232",
  • "identity_card_created_at": "2015-23-01",
  • "identity_card_created_by": "Stadt Köln",
  • "identity_card_expires_at": "2035-22-01",
  • "country": "DE",
  • "city": "Köln",
  • "street": "Musterstraße",
  • "street_number": "3a",
  • "postal_code": "50273",
  • "previous_address": {
    • "city": "Tunis",
    • "street": "Habib 5",
    • "street_number": "15",
    • "postal_code": "9100"
    },
  • "resident_since": "1995-04-01",
  • "bank_account": "Max Mustermann",
  • "bank_institution": "Musterbank Köln",
  • "iban": "DE12500105170648489890",
  • "bic": "DABAIE2D",
  • "tax_id": "633876272618",
  • "external_id": "user-123XX",
  • "full_name_reversed": "Mustermann, Max",
  • "created_at": "2018-09-15T15:28:23+00:00",
  • "updated_at": "2018-09-23T12:13:42+00:00",
  • "created_by": 2,
  • "updated_by": 34,
  • "advisor": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "channel": {
    • "id": 232,
    • "name": "Muster Tag",
    • "is_system": 0,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "creator": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "editor": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "owner": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "partners": [
    • {
      }
    ],
  • "sourceable": {
    • "id": 24,
    • "channel_id": 3,
    • "name": "Muster Quelle",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "tags": [
    • {
      }
    ],
  • "abilities": {
    • "can_edit": true,
    • "can_delete": false
    }
}

Update customer.

Update a customer.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/x-www-form-urlencoded
One of
email
required
string <email> [ 1 .. 255 ]
Default: null

The customers email address. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

first_name
required
string [ 1 .. 255 ]
Default: ""

The customers first name.

last_name
required
string [ 1 .. 255 ]
Default: null

The customers last name

owner_id
integer
Default: null

The id of the owner of the customer

advisor_id
integer
Default: null

The id of the adviser

advisor_type
string
Default: null
Enum: "intermediary" "user"

The type of the advisor

channel_id
integer
Default: null

The id of the source channel

sourceable_id
integer
Default: null

The id of the adviser

sourceable_type
string
Default: null
Enum: "customer" "intermediary" "source"

The type of the source.

salutation
string
Default: ""
Enum: "Frau" "Herr"

The customers salutation.

title
string
Default: null
Enum: "Dr." "Prof." "Prof. Dr."

The customers title.

email_office
string <email> [ 1 .. 255 ]
Default: null

The customers office email address. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

birthday
string <date>
Default: null

The birthday of the customer.

birth_place
string [ 1 .. 255 ]
Default: null

The customers birth place.

birth_name
string [ 1 .. 255 ]
Default: null

The customers birth name.

phone_private
string [ 1 .. 255 ]
Default: null

The customers primary private phone number. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

phone_office
string [ 1 .. 255 ]
Default: null

The customers primary office phone number. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

mobile
string [ 1 .. 255 ]
Default: null

The customers primary mobile phone number. One contact information is required. It could be either email, email_office, phone_private, phone_office or mobile.

fax
string [ 1 .. 255 ]
Default: null

The customers primary fax number.

do_not_disturb
boolean
Default: false

Whether or not the customer wants to be contacted.

homepage
string [ 1 .. 255 ]
Default: null

Whether or not the customer wants to be contacted.

industry_id
number
Default: null
Enum: 1 10 11 12 13 … 34 more

The industry values are:

  • 1 = Architektur & Bauwesen
  • 2 = Automobilindustrie
  • 3 = Baugewerbe
  • 4 = Beratung/Consulting
  • 5 = Bildungswesen
  • 6 = Coaching
  • 7 = Computer Software
  • 8 = Design
  • 9 = Dienstleistungen
  • 10 = Druck
  • 11 = Einzelhandel
  • 12 = Elektrotechnik
  • 13 = Erneuerbare Energiequellen & Umwelt
  • 14 = Finanzdienstleistungen
  • 15 = Fotografie
  • 16 = Freizeit & Tourismus
  • 17 = Gesundheit & Fitness
  • 18 = Gesundheitswesen
  • 19 = Großhandel
  • 20 = Hotel & Gaststätten
  • 21 = Immobilien
  • 22 = Informationstechnologie & -dienste
  • 23 = Internet
  • 24 = Lebensmittel
  • 25 = Logistik & Zulieferung
  • 26 = Marketing & Werbung
  • 27 = Maschinenbau & Betriebstechnik
  • 28 = Medienproduktion
  • 29 = Metallindustrie/-verarbeitung
  • 30 = Öffentlichkeitsarbeit & Kommunikation
  • 31 = Personalbeschaffung
  • 32 = Personalwesen
  • 33 = Rechtsberatung
  • 34 = Sport
  • 35 = Steuerberatung/Wirtschaftsprüfung
  • 36 = Telekommunikation
  • 37 = Unternehmensberatung
  • 38 = Veranstaltungsdienstleistungen
  • 39 = Versicherungen
company
string [ 1 .. 255 ]
Default: null

The company the customer works for.

employment_state
string
Default: null
Enum: "permanent" "temporary"

The customers employment state.

employer_in_germany
boolean
Default: null

Whether or not the employer is situated in germany.

job
string [ 1 .. 255 ]
Default: null

The customers job.

employed_since
string <date>
Default: null

The date since the customer works in his current job.

employment_temporary_until
string <date>
Default: null

The date until the customer works in his temporary job.

occupational_group_id
number
Default: null
Enum: 1 10 2 3 4 … 5 more

The occupational group values are:

  • 1 = Angestelle(r)
  • 2 = Leitende(r) Angestellte(r)
  • 3 = Arbeiter(in)
  • 4 = Beamte(r)
  • 5 = Rentner(in)
  • 6 = Hausfrau-/Mann
  • 7 = Selbstständig
  • 8 = Freiberufler(in)
  • 9 = Arbeitslos
  • 10 = Sonstiges
retires_at
string <date>
Default: null

The date when the customer will retire.

nationality
string
Default: null
Enum: "AD" "AE" "AF" "AG" "AL" … 183 more

The nationality.

marital_status
string
Default: null
Enum: "Geschieden" "Getrennt lebend" "Ledig" "Verheiratet" "Verpartnert" … 1 more

The marital status of the customer.

marital_property
string
Default: null
Enum: "Gesetzlicher Güterstand" "Gütergemeinschaft" "Gütertrennung"

The marital property of the customer.

identity_card
string [ 1 .. 255 ]
Default: null

The identy card number of the customer.

identity_card_created_at
string <date>
Default: null

The date when identity card was created.

identity_card_created_by
string
Default: null

The authority that authorized the identity card.

identity_card_expires_at
string <date>
Default: null

The date when identity card expires.

country
string [ 2 .. 2 ]
Default: null

The country the customer lives in (ISO-3166 Alpha 2 code i.e. "DE").

city
string [ 1 .. 255 ]
Default: null

The city the customer lives in.

street
string [ 1 .. 255 ]
Default: null

The street the customer lives in.

street_number
string [ 1 .. 100 ]
Default: null

The street number of the customer.

postal_code
string [ 3 .. 12 ]
Default: null

The customers postal code (zip).

object
Default: {}

The customer's old address.

resident_since
string <date>
Default: null

The date since the customer staying in the current residence.

bank_account
string [ 2 .. 70 ]
Default: null

The customers bank account name.

bank_institution
string [ 2 .. 255 ]
Default: null

The customers bank name.

iban
string [ 22 .. 34 ]
Default: null

The customers iban.

bic
string [ 11 .. 22 ]
Default: null

The customers bic.

tax_id
string [ 11 .. 11 ]
Default: null

The customers tax id.

external_id
string
Default: null

An optional custom identifier.

created_at
string <date-time>
Default: null

The date when the customer was created (UTC).

Responses

Response samples

Content type
application/json
{
  • "id": 2675,
  • "owner_id": 28,
  • "advisor_id": 12,
  • "advisor_type": "intermediary",
  • "channel_id": 3,
  • "sourceable_id": 12,
  • "sourceable_type": "intermediary",
  • "salutation": "Herr",
  • "title": "Dr.",
  • "first_name": "Max",
  • "last_name": "Mustermann",
  • "email": "max-mustermann@mustermail.de",
  • "email_office": "max-mustermann@muster-gmbh.de",
  • "birthday": "1985-09-15",
  • "birth_place": "Musterstadt",
  • "birth_name": "Mustermännchen",
  • "phone_private": "+49 231-23752122",
  • "phone_office": "+49 231-27519062",
  • "mobile": "+49 171-242233212",
  • "fax": "+49 231-324553332",
  • "do_not_disturb": false,
  • "homepage": "https://www.fincrm.de",
  • "industry_id": 3,
  • "company": "Mustermann GmbH",
  • "employment_state": "permanent",
  • "employer_in_germany": true,
  • "job": "Online Redakteur",
  • "employed_since": "2014-01-01",
  • "employment_temporary_until": "2030-01-01",
  • "occupational_group_id": 1,
  • "retires_at": "2038-01-01",
  • "nationality": "DE",
  • "marital_status": "Verheiratet",
  • "marital_property": "Gesetzlicher Güterstand",
  • "identity_card": "A2973NBUG2232",
  • "identity_card_created_at": "2015-23-01",
  • "identity_card_created_by": "Stadt Köln",
  • "identity_card_expires_at": "2035-22-01",
  • "country": "DE",
  • "city": "Köln",
  • "street": "Musterstraße",
  • "street_number": "3a",
  • "postal_code": "50273",
  • "previous_address": {
    • "city": "Tunis",
    • "street": "Habib 5",
    • "street_number": "15",
    • "postal_code": "9100"
    },
  • "resident_since": "1995-04-01",
  • "bank_account": "Max Mustermann",
  • "bank_institution": "Musterbank Köln",
  • "iban": "DE12500105170648489890",
  • "bic": "DABAIE2D",
  • "tax_id": "633876272618",
  • "external_id": "user-123XX",
  • "full_name_reversed": "Mustermann, Max",
  • "created_at": "2018-09-15T15:28:23+00:00",
  • "updated_at": "2018-09-23T12:13:42+00:00",
  • "created_by": 2,
  • "updated_by": 34,
  • "advisor": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "channel": {
    • "id": 232,
    • "name": "Muster Tag",
    • "is_system": 0,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "creator": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "editor": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "owner": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "partners": [
    • {
      }
    ],
  • "sourceable": {
    • "id": 24,
    • "channel_id": 3,
    • "name": "Muster Quelle",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "tags": [
    • {
      }
    ],
  • "abilities": {
    • "can_edit": true,
    • "can_delete": false
    }
}

Delete customer.

Delete a customer by id.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that need to be deleted

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "error_description": "Additional information about the bad request.",
  • "message": "Additional information about the bad request."
}

List Properties of Customer.

Returns a list of properties of a customer matching the filter criterias.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the note should be attached to

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 14,
    • "customer_id": 12,
    • "type_id": 1,
    • "usage_id": 2,
    • "street": "Musterstraße",
    • "street_number": "2a",
    • "postal_code": 50977,
    • "city": "Musterstadt",
    • "construction_year": 2018
    }
]

Create Property for Customer.

Create a new property for the customer.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the property should be attached to

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema:
One of
city
required
string or null [ 1 .. 255 ]
Default: null

The city of the property. Required when postal code is not set.

type_id
integer or null
Default: null
Enum: 1 10 2 3 4 … 5 more

The property type:

  • 1 = Eigentumswohnung
  • 2 = Einfamilienhaus
  • 3 = Reiheneckhaus
  • 4 = Reihenmittelhaus
  • 5 = Zweifamilienhaus
  • 6 = Mehrfamilienhaus
  • 7 = Wohn-/Geschäftshaus
  • 8 = Doppelhaushälfte
  • 9 = Grundstück
  • 10 = Sonstiges
usage_id
integer or null
Default: null
Enum: 1 2 3

The property usage:

  • 1 = Eigennutzung
  • 2 = Fremdnutzung
  • 3 = Eigen- & Fremdnutzung
street
string or null [ 1 .. 255 ]
Default: null

The street of the property

street_number
string or null [ 1 .. 100 ]
Default: null

The street number of the property

postal_code
string or null [ 1 .. 12 ]
Default: null

The postal code of the property. Required when city is not set.

construction_year
integer or null [ 1000 .. 9999 ]

Responses

Request samples

Content type
{
  • "type_id": 1,
  • "usage_id": 2,
  • "street": "Musterstraße",
  • "street_number": "2a",
  • "postal_code": 50977,
  • "city": "Musterstadt",
  • "construction_year": 2018
}

Response samples

Content type
application/json
{
  • "id": 14,
  • "customer_id": 12,
  • "type_id": 1,
  • "usage_id": 2,
  • "street": "Musterstraße",
  • "street_number": "2a",
  • "postal_code": 50977,
  • "city": "Musterstadt",
  • "construction_year": 2018
}

List Purposes of Customer.

Returns a list of purposes of a customer matching the filter criterias.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the note should be attached to

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 14,
    • "customer_id": 12,
    • "property_id": 13,
    • "type_id": 1,
    • "financial_demand": 500000,
    • "state": "ON_HOLD",
    • "state_reason": "LOOKING_FOR_PROPERTY",
    • "state_note": null,
    • "state_since": "2022-09-23T12:13:42+00:00",
    • "stage_id": 1,
    • "channel_id": 3,
    • "sourceable_id": 12,
    • "sourceable_type": "intermediary"
    }
]

Create Purpose for Customer.

Create a new purpose for the customer.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the property should be attached to

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema:
type_id
required
integer
Enum: 1 10 11 12 2 … 7 more

The purpose type:

  • 1 = Neubau - eigenes Bauvorhaben
  • 2 = Kauf - Bestandsimmobilie
  • 3 = Kauf - Neubau vom Bauträger
  • 4 = Kauf - Grundstück
  • 5 = Modernisierung
  • 6 = Anschlussfinanzierung / Umschuldung
  • 7 = Kapitalbeschaffung
  • 8 = Kapitalanlage - Versicherung
  • 9 = Kapitalanlage - Bausparvertrag
  • 10 = Kapitalanlage - Fond
  • 11 = Konsumentenkredit
  • 12 = Versicherung
property_id
integer or null
Default: null

The id of the property

financial_demand
number or null <double>
Default: null

The financial demand of the purpose

state
string or null
Default: "ACTIVE"
Enum: "ACTIVE" "LOST" "ON_HOLD" "WON" null

The purpose state:

  • ACTIVE = Aktiv
  • ON_HOLD = Inaktiv
  • LOST = Verloren
  • WON = Gewonnen
state_reason
string or null
Default: null
Enum: "INTEREST_LOST" "LOOKING_FOR_PROPERTY" "LOST_TO_COMPETITOR" "NEGATIVE_CREDIT_CHECK" "NOT_AFFORDABLE" … 7 more

The state reason for purposes in state ON_HOLD or LOST On Hold Reasons:

  • LOOKING_FOR_PROPERTY = Objektsuche
  • WAITING_FOR_DOCUMENTS = Warten auf Unterlagen
  • WAITING_FOR_RESPONSE = Warten auf Rückmeldung
  • OTHER = Anderer Grund

Loss Reasons:

  • WRONG_INFORMATION = Falsche Angaben
  • LOST_TO_COMPETITOR = An Wettbewerber verloren
  • NO_RESPONSE = Keine Rückmeldung
  • NEGATIVE_CREDIT_CHECK = Negative Kreditprüfung
  • NOT_AFFORDABLE = Nicht finanzierbar
  • OBJECT_LOST = Objekt verloren
  • INTEREST_LOST = Interesse verloren
  • OTHER = Anderer Grund \n
state_note
string or null
Default: null

Custom state note for purposes in state ON_HOLD or LOST

stage_id
integer or null
Default: "[ID_OF_FIRST_STAGE]"

The id of the pipeline stage

channel_id
integer or null
Default: null

The id of the channel

sourceable_id
integer or null
Default: null

The id of the sourceable

sourceable_type
string or null
Default: null
Enum: "customer" "intermediary" "source"

The type of the source.

Responses

Request samples

Content type
{
  • "property_id": 13,
  • "type_id": 1,
  • "financial_demand": 500000,
  • "state": "ON_HOLD",
  • "state_reason": "LOOKING_FOR_PROPERTY",
  • "state_note": null,
  • "stage_id": 1,
  • "channel_id": 3,
  • "sourceable_id": 12,
  • "sourceable_type": "intermediary"
}

Response samples

Content type
application/json
{
  • "id": 14,
  • "customer_id": 12,
  • "property_id": 13,
  • "type_id": 1,
  • "financial_demand": 500000,
  • "state": "ON_HOLD",
  • "state_reason": "LOOKING_FOR_PROPERTY",
  • "state_note": null,
  • "state_since": "2022-09-23T12:13:42+00:00",
  • "stage_id": 1,
  • "channel_id": 3,
  • "sourceable_id": 12,
  • "sourceable_type": "intermediary"
}

List Notes of Customer.

Returns a list of notes for a customer matching the filter criterias.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the note should be attached to

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 23,
    • "object_id": 12,
    • "object_type": "customer",
    • "text": "This is my new note.",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 8,
    • "updated_by": 143
    }
]

Create Note for Customer.

Create a new note for the customer.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the note should be attached to

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/x-www-form-urlencoded
text
required
string [ 3 .. 16777215 ]

The text of the note

Responses

Response samples

Content type
application/json
{
  • "id": 23,
  • "object_id": 12,
  • "object_type": "customer",
  • "text": "This is my new note.",
  • "created_at": "2018-09-15T15:28:23+00:00",
  • "updated_at": "2018-09-23T12:13:42+00:00",
  • "created_by": 8,
  • "updated_by": 143
}

Show Note of Customer.

Get information about a note of a customer by id.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 33

The id of the customer

noteId
required
integer >= 1
Example: 234

The id of the note

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
{
  • "id": 23,
  • "object_id": 12,
  • "object_type": "customer",
  • "text": "This is my new note.",
  • "created_at": "2018-09-15T15:28:23+00:00",
  • "updated_at": "2018-09-23T12:13:42+00:00",
  • "created_by": 8,
  • "updated_by": 143
}

Update Note of Customer.

Update a note of a customer.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 44

The id of the customer

noteId
required
integer >= 1
Example: 875

The id of the note

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/x-www-form-urlencoded
text
required
string [ 3 .. 16777215 ]

The text of the note

Responses

Response samples

Content type
application/json
{
  • "id": 2675,
  • "owner_id": 28,
  • "advisor_id": 12,
  • "advisor_type": "intermediary",
  • "channel_id": 3,
  • "sourceable_id": 12,
  • "sourceable_type": "intermediary",
  • "salutation": "Herr",
  • "title": "Dr.",
  • "first_name": "Max",
  • "last_name": "Mustermann",
  • "email": "max-mustermann@mustermail.de",
  • "email_office": "max-mustermann@muster-gmbh.de",
  • "birthday": "1985-09-15",
  • "birth_place": "Musterstadt",
  • "birth_name": "Mustermännchen",
  • "phone_private": "+49 231-23752122",
  • "phone_office": "+49 231-27519062",
  • "mobile": "+49 171-242233212",
  • "fax": "+49 231-324553332",
  • "do_not_disturb": false,
  • "homepage": "https://www.fincrm.de",
  • "industry_id": 3,
  • "company": "Mustermann GmbH",
  • "employment_state": "permanent",
  • "employer_in_germany": true,
  • "job": "Online Redakteur",
  • "employed_since": "2014-01-01",
  • "employment_temporary_until": "2030-01-01",
  • "occupational_group_id": 1,
  • "retires_at": "2038-01-01",
  • "nationality": "DE",
  • "marital_status": "Verheiratet",
  • "marital_property": "Gesetzlicher Güterstand",
  • "identity_card": "A2973NBUG2232",
  • "identity_card_created_at": "2015-23-01",
  • "identity_card_created_by": "Stadt Köln",
  • "identity_card_expires_at": "2035-22-01",
  • "country": "DE",
  • "city": "Köln",
  • "street": "Musterstraße",
  • "street_number": "3a",
  • "postal_code": "50273",
  • "previous_address": {
    • "city": "Tunis",
    • "street": "Habib 5",
    • "street_number": "15",
    • "postal_code": "9100"
    },
  • "resident_since": "1995-04-01",
  • "bank_account": "Max Mustermann",
  • "bank_institution": "Musterbank Köln",
  • "iban": "DE12500105170648489890",
  • "bic": "DABAIE2D",
  • "tax_id": "633876272618",
  • "external_id": "user-123XX",
  • "full_name_reversed": "Mustermann, Max",
  • "created_at": "2018-09-15T15:28:23+00:00",
  • "updated_at": "2018-09-23T12:13:42+00:00",
  • "created_by": 2,
  • "updated_by": 34,
  • "advisor": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "channel": {
    • "id": 232,
    • "name": "Muster Tag",
    • "is_system": 0,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "creator": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "editor": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "owner": {
    • "id": 24,
    • "group_id": 123,
    • "company_id": 321,
    • "external_id": "AE3224",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "mobile": "+49 171-242233212",
    • "phone_office": "+49 231-27519062",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "permissions": {
      },
    • "is_active": true,
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "partners": [
    • {
      }
    ],
  • "sourceable": {
    • "id": 24,
    • "channel_id": 3,
    • "name": "Muster Quelle",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    },
  • "tags": [
    • {
      }
    ],
  • "abilities": {
    • "can_edit": true,
    • "can_delete": false
    }
}

Delete Note of Customer.

Delete a single note of a customer by id.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 23

The id of the customer

noteId
required
integer >= 1
Example: 873

The id of the note

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "error_description": "Additional information about the bad request.",
  • "message": "Additional information about the bad request."
}

List Tags of Customer.

Returns a list of all the tags for a customer.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the tag should be assigned to

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 24,
    • "name": "Muster Tag",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 3
    }
]

Assign Tags to Customer.

Assign a tag to the customer.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the tag should be assigned to

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/x-www-form-urlencoded
tag_ids
required
Array of integers

The ids of tags

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 24,
    • "name": "Muster Tag",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 3
    }
]

Unassign Tags from the Customer.

Unassign a tag from the customer.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer that the tag should be unassigned from

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/x-www-form-urlencoded
tag_ids
required
Array of integers

The ids of tags

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 24,
    • "name": "Muster Tag",
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 3
    }
]

Intermediaries

All Endpoints related to the intermediary entity.

List intermediaries

Returns a list of intermediaries matching the filter criterias.

Authorizations:
OAuth2PersonalAccessToken
query Parameters
company_id
integer
Example: company_id=12

Filter the results by a company id

owner_id
integer
Example: owner_id=2

Filter the result by an owner id. Allowed operators: in

is_active
boolean
Example: is_active=true

Filter the results by the status is_active

email
string
Example: email=max.mustermann@musterweb.de

Filter the results by an email of the intermediary. Allowed operators: like

postal_code
string
Example: postal_code=50362

Filter the result by postal code of the intermediary. Allowed operators: like

street
string
Example: street=Musterstraße

Filter the result by street of the intermediary. Allowed operators: like

city
string
Example: city=Musterstadt

Filter the result by city of the intermediary. Allowed operators: like

salutation
Array of any
Items Enum: 1 2
Example: salutation=1

'Filter the results by salutation/gender of the intermediary. Allowed operators: in.'

first_name
string
Example: first_name=max

Filter the results by first name of the intermediary.

last_name
string
Example: last_name=mustermann

Filter the results by last name of the intermediary.

tags
integer
Example: tags=2

Filter the results by tags of the intermediary

created_at_period
string
Enum: "current_month" "current_week" "current_year" "last_month" "last_week" … 3 more
Example: created_at_period=current_year

Filter the results by created_at period

created_at_start
string <date>
Example: created_at_start=2019-01-25

Filter the results by created_at start date.

created_at_end
string <date>
Example: created_at_end=2019-01-25

Filter the results by created_at end date.

updated_at_end
string <date>
Example: updated_at_end=2019-01-25

Filter the results by updated_at end date.

updated_at
string <date>
Example: updated_at=2018-09-23T12:13:42

Filter the results by a updated_at.

updated_at_period
string
Enum: "current_month" "current_week" "current_year" "last_month" "last_week" … 3 more
Example: updated_at_period=current_year

Filter the results by a updated_at period.

updated_at_start
string <date>
Example: updated_at_start=2019-01-25

Filter the results by updated_at start date.

sort
string
Enum: "address" "birthday" "company_id" "created_at" "email" … 12 more
Example: sort=-updated_at

Sort intermediaries by a field. Prepend - to a field to sort in descending order.

with
Array of arrays
Items Enum: "company" "owner" "tags"
Example: with=owner,partners

Load nested resources. Multiple values separated by comma are allowed.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 24,
    • "owner_id": 28,
    • "company_id": 321,
    • "is_active": true,
    • "salutation": "Herr",
    • "title": "Dr.",
    • "first_name": "Max",
    • "last_name": "Mustermann",
    • "email": "max-mustermann@mustermail.de",
    • "birthday": "1985-09-15",
    • "birth_place": "Musterstadt",
    • "birth_name": "Mustermännchen",
    • "position": "Teamleiter",
    • "phone_private": "+49 231-23752122",
    • "phone_office": "+49 231-27519062",
    • "mobile": "+49 171-242233212",
    • "fax": "+49 231-324553332",
    • "city": "Köln",
    • "street": "Musterstraße",
    • "street_number": "3a",
    • "postal_code": "50273",
    • "billing_address": 1,
    • "billing_account": 1,
    • "tax_number": "633876272618",
    • "vat_number": "2376273626511",
    • "tax_office": "Finanzamt Köln",
    • "is_small_business": true,
    • "bank_account": "Max Mustermann",
    • "bank_institution": "Musterbank Köln",
    • "iban": "DE12500105170648489890",
    • "bic": "DABAIE2D",
    • "registration_authority": "Amtsgericht Köln",
    • "registration_number": "HRB 236267",
    • "broker_qualifications": [
      ],
    • "broker_certificates": [
      ],
    • "created_at": "2018-09-15T15:28:23+00:00",
    • "updated_at": "2018-09-23T12:13:42+00:00",
    • "created_by": 2,
    • "updated_by": 34
    }
]

Institutes

All Endpoints related oauth institute entity.

List institutes

Returns a list of institutes matching the filter criterias.

Authorizations:
OAuth2PersonalAccessToken
query Parameters
name
string
Example: name=Allianz

Filter the results by name of the institute. Allowed operators: like

postal_code
string
Example: postal_code=50933

Filter the result by postal code of the institute. Allowed operators: like

street
string
Example: street=Aachener Str.

Filter the result by street of the institute. Allowed operators: like

city
string
Example: city=Köln

Filter the result by city of the institute. Allowed operators: like

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 21,
    • "name": "Sparkasse Aachen",
    • "city": "Aachen",
    • "street": "Musterstraße",
    • "postal_code": "12345"
    }
]

Create institute

Create a new institute.

Authorizations:
OAuth2PersonalAccessToken
header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/x-www-form-urlencoded
name
required
string
Default: ""

The name of the institute.

city
string [ 1 .. 255 ]
Default: ""

The city of the institute.

street
string [ 1 .. 255 ]
Default: ""

The street of the institute.

postal_code
string [ 1 .. 5 ]
Default: ""

The postal code of the institute.

Responses

Response samples

Content type
application/json
{
  • "id": 21,
  • "name": "Sparkasse Aachen",
  • "city": "Aachen",
  • "street": "Musterstraße",
  • "postal_code": "12345"
}

Show institute

Get information about a institute by id.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
instituteId
required
integer >= 1
Example: 12

The id of the institute

query Parameters
with
Array of arrays
Items Enum: "creator" "editor"
Example: with=creator,editor

Load nested resources. Multiple values separated by comma are allowed.

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
{
  • "id": 21,
  • "name": "Sparkasse Aachen",
  • "city": "Aachen",
  • "street": "Musterstraße",
  • "postal_code": "12345"
}

Update institute

Update an institute.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
instituteId
required
integer >= 1
Example: 12

The id of the institute

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Request Body schema: application/x-www-form-urlencoded
name
required
string
Default: ""

The name of the institute.

city
string [ 1 .. 255 ]
Default: ""

The city of the institute.

street
string [ 1 .. 255 ]
Default: ""

The street of the institute.

postal_code
string [ 1 .. 5 ]
Default: ""

The postal code of the institute.

Responses

Response samples

Content type
application/json
{
  • "id": 21,
  • "name": "Sparkasse Aachen",
  • "city": "Aachen",
  • "street": "Musterstraße",
  • "postal_code": "12345"
}

Delete institute

Delete a institute by id.

Authorizations:
OAuth2PersonalAccessToken
path Parameters
instituteId
required
integer >= 1
Example: 12

The id of the institute that need to be deleted

header Parameters
Accept
string
Value: "application/json"
Example: application/json

The Accept header advertises which content types the client is able to understand.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "error_description": "Additional information about the bad request.",
  • "message": "Additional information about the bad request."
}

Secondary Entities

All Endpoints related to the secondary entities.

List industries.

Returns a list of industries matching the filter criterias.

Authorizations:
OAuth2PersonalAccessToken

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 21,
    • "name": "Immobilien"
    }
]

Security

All Endpoints related oauth authentication & security

Authorize OAuth App

Shows a OAuth authorization request view and redirects back to the redirect uri. Important: this route is not part of the api url namespace. The full url is https://{subdomain}.fincrm.de/oauth/authorize.

Authorizations:
OAuth2PersonalAccessToken
query Parameters
client_id
required
integer
Example: client_id=234

Defined when the client was registered

redirect_uri
required
string
Example: redirect_uri=https://my-app.com/oauth/callback

Defined when the client was registered

response_type
required
string
Example: response_type=code

Response Type must be code

scope
string
Example: scope=scope1,scope2,scope3

Fincrm does not support api scopes yet.

state
string
Example: state=my-app-state

An opaque value used by the client to maintain state between the request and callback

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "Additional information about the bad request.",
  • "message": "Additional information about the bad request.",
  • "hint": "Additional information about the bad request."
}

Get Access Token

Returns an access token in exchange for the code.

Authorizations:
OAuth2PersonalAccessToken
query Parameters
client_id
required
integer
Example: client_id=123

Defined when the client was registered

client_secret
required
string
Example: client_secret=bd72mpsbn27vavalf83nufbdewdd

Defined when the client was registered

grant_type
required
string
Example: grant_type=authorization_code

Grant Type must be authorization_code

redirect_uri
required
string
Example: redirect_uri=https://my-app.com/oauth/callback

Defined when the client was registered

code
required
string
Example: code=dbwaid72gbde2d7b2dlkagd727

Authorization code that was issued by fincrm when the user approved the authorization request

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM",
  • "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM",
  • "expires_in": 1223
}

Refresh Access Token

Returns a new access token in exchange for the refresh token.

Authorizations:
OAuth2PersonalAccessToken
query Parameters
client_id
required
integer
Example: client_id=123

Defined when the client was registered

client_secret
required
string
Example: client_secret=bd72mpsbn27vavalf83nufbdewdd

Defined when the client was registered

grant_type
required
string
Example: grant_type=refresh_token

Grant Type must be refresh_token

refresh_token
required
string
Example: refresh_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM

Provided when the access token was issued

scope
string
Example: scope=scope1,scope2,scope3

Fincrm does not support api scopes yet.

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM",
  • "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM",
  • "expires_in": 1223
}