FinCRM API (alpha) (0.0.3)

Download OpenAPI specification:Download

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.

Changelog

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

[0.0.3] - 2019-06-05

  • 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://{customerId}.fincrm.de/api/v1/oauth/authorize to https://{customerId}.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://{customerId}.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://{customerId}.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://{customerId}.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
authorizationCode OAuth Flow
Authorization URL: https://{customerId}.fincrm.de/oauth/authorize
Token URL: https://{customerId}.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

Customers

All Endpoints related to the customer entity.

List customers.

get /customers
https://{customerId}.fincrm.de/api/v1/customers

Returns a list of customers matching the filter criterias.

query Parameters
advisor
string
Example: "advisor=2#HPE\\Domain\\Core\\Acl\\Users\\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:"yesterday" "today" "tomorrow" "last_week" "current_week" "next_week" "last_month" "current_month" "next_month" "last_3_month" "next_3_month" "last_6_month" "next_6_month"
Example: "birthday=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_at_end
string <date>
Example: "created_at_end=2019-01-25"

Filter the results by created_at end date.

created_at_period
string
Enum:"yesterday" "today" "last_week" "current_week" "last_month" "current_month" "last_year" "current_year"
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.

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

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

fields
array
Items Enum:"id" "first_name" "last_name"
Example: "fields=id,first_name"

Show only a subset of the customers field.

first_name
string
Example: "first_name=max"

Filter the results by first name of the customer.

job
string
Example: "job=Architekt"

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

last_name
string
Example: "last_name=mustermann"

Filter the results by last name 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.

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:"salutation" "name" "first_name" "last_name" "email" "email_office" "address" "phone_private" "phone_office" "fax" "birthday" "homepage" "job" "company" "created_at" "updated_at" "do_not_disturb" "owner_id" "advisor_id"
Example: "sort=-updated_at"

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

sourceable
string
Example: "sourceable=2#HPE\\Domain\\Intermediation\\Intermediaries\\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_period
string
Enum:"yesterday" "today" "last_week" "current_week" "last_month" "current_month" "last_year" "current_year"
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
Items Enum:"owner" "partners" "purposes" "advisor"
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

200

OK.

400

Bad Request.

401

Unauthorized.

403

Forbidden.

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Create customer.

post /customers
https://{customerId}.fincrm.de/api/v1/customers

Create a new 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
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

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

The customers salutation.

advisor_id
integer
Default: null

The id of the adviser

advisor_type
string
Default: null
Enum:"HPE\\Domain\\Core\\Acl\\Users\\User" "HPE\\Domain\\Intermediation\\Intermediaries\\Intermediary"

The type of the advisor

bank_account
string [ 2, .. 255 ]
Default: null

The customers bank account name.

bank_institution
string [ 2, .. 255 ]
Default: null

The customers bank name.

bic
string [ 11, .. 22 ]
Default: null

The customers bic.

birth_name
string [ 1, .. 255 ]
Default: null

The customers birth name.

birth_place
string [ 1, .. 255 ]
Default: null

The customers birth place.

birthday
string <date>
Default: null

The birthday of the customer.

channel_id
integer
Default: null

The id of the source channel

city
string [ 1, .. 255 ]
Default: null

The city the customer lives in.

company
string [ 1, .. 255 ]
Default: null

The company the customer works for.

created_at
string <date-time>
Default: null

The date when the customer was created.

do_not_disturb
boolean
Default: false

Whether or not the customer wants to be contacted.

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.

employed_since
string <date>
Default: null

The date since the customer works in his current job.

fax
string [ 1, .. 255 ]
Default: null

The customers primary fax number.

homepage
string [ 1, .. 255 ]
Default: null

Whether or not the customer wants to be contacted.

iban
string [ 22, .. 34 ]
Default: null

The customers iban.

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.

industry_id
number
Default: null
Enum:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39

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
job
string [ 1, .. 255 ]
Default: null

The customers job.

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

The marital property of the customer.

marital_status
string
Default: null
Enum:"Ledig" "Verheiratet" "Geschieden" "Getrennt lebend" "Verwitwet" "Verpartnert"

The marital status of the customer.

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.

nationality
string
Default: null
Enum:"AF" "EG" "AL" "DZ" "AD" "AO" "AG" "GQ" "AR" "AM" "AZ" "ET" "AU" "BS" "BH" "BD" "BB" "BE" "BZ" "BJ" "BT" "BO" "BA" "BW" "BR" "BN" "BG" "BF" "BI" "CL" "CN" "NZ" "CR" "CI" "DK" "DE" "DM" "DJ" "SV" "ER" "EE" "FJ" "FI" "FR" "GA" "GM" "GE" "GH" "GD" "GR" "GT" "GN" "GW" "GY" "HT" "HN" "IN" "ID" "IQ" "IR" "IE" "IS" "IL" "IT" "JM" "JP" "YE" "JO" "KH" "CM" "CA" "CV" "KZ" "QA" "KE" "KG" "KI" "CO" "KM" "CG" "CD" "KP" "XK" "HR" "CU" "KW" "LA" "LS" "LV" "LB" "LR" "LI" "LT" "LU" "MG" "MW" "MY" "MV" "ML" "MT" "MA" "MH" "MR" "MU" "MK" "MX" "FM" "MD" "MC" "MN" "ME" "MZ" "MM" "NA" "NR" "NP" "NI" "NL" "NE" "NG" "NO" "OM" "PK" "PW" "PA" "PG" "PY" "PE" "PH" "PL" "PT" "RW" "RO" "RU" "SB" "ZM" "WS" "SM" "ST" "SA" "SE" "CH" "SN" "RS" "SC" "SL" "ZW" "SG" "SK" "SI" "SO" "ES" "LK" "LC" "VC" "ZA" "SD" "SS" "SR" "SZ" "SY" "TJ" "TZ" "TH" "TG" "TO" "TT" "TD" "CZ" "TN" "TR" "TM" "TV" "UG" "UA" "HU" "UY" "UZ" "VU" "VA" "VE" "AE" "US" "GB" "VN" "BY" "CF" "CY"

The nationality.

occupational_group_id
number
Default: null
Enum:1 2 3 4 5 6 7 8 9 10

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
owner_id
integer
Default: null

The id of the owner of the customer

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.

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.

postal_code
string [ 3, .. 12 ]
Default: null

The customers postal code (zip).

retires_at
string <date>
Default: null

The date when the customer will retire.

sourceable_id
integer
Default: null

The id of the adviser

sourceable_type
string
Default: null
Enum:"HPE\\Domain\\Intermediation\\Intermediaries\\Intermediary" "HPE\\Domain\\Customers\\Customers\\Customer" "HPE\\Domain\\Settings\\Sources\\Source"

The type of the source.

street
string [ 1, .. 255 ]
Default: null

The street the customer lives in.

street_number
string [ 1, .. 5 ]
Default: null

The street number of the customer.

tax_id
string [ 11 .. 11 ]
Default: null

The customers tax id.

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

The customers title.

Responses

201

Created.

400

Bad Request.

401

Unauthorized.

403

Forbidden.

422

Validation Error.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 2675,
  • "owner_id": 28,
  • "advisor_id": 12,
  • "advisor_type": "HPE\Domain\Intermediation\Intermediaries\Intermediary",
  • "channel_id": 3,
  • "sourceable_id": 12,
  • "sourceable_type": "HPE\Domain\Intermediation\Intermediaries\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",
  • "job": "Online Redakteur",
  • "employed_since": "2014-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": "2016-11-01T00:00:00.000Z",
  • "identity_card_created_by": "Stadt Köln",
  • "identity_card_expires_at": "2036-10-01T00:00:00.000Z",
  • "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_id": "633876272618",
  • "full_name_reversed": "Mustermann, Max",
  • "created_at": "2018-09-15T15:28:23+01:00",
  • "updated_at": "2018-09-23T12:13:42+01:00",
  • "created_by": 2,
  • "updated_by": 34,
  • "advisor":
    {
    },
  • "channel":
    {
    },
  • "creator":
    {
    },
  • "editor":
    {
    },
  • "owner":
    {
    },
  • "partners":
    [
    ],
  • "sourceable":
    {
    },
  • "tags":
    [
    ]
}

Show customer.

get /customers/{customerId}
https://{customerId}.fincrm.de/api/v1/customers/{customerId}

Get information about a customer by id.

path Parameters
customerId
required
integer >= 1
Example: 12

The id of the customer

query Parameters
with
array
Items Enum:"owner" "advisor" "creator" "editor" "channel" "sourceable" "tags"
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

200

OK.

400

Bad Request.

401

Unauthorized.

403

Forbidden.

404

Not found.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 2675,
  • "owner_id": 28,
  • "advisor_id": 12,
  • "advisor_type": "HPE\Domain\Intermediation\Intermediaries\Intermediary",
  • "channel_id": 3,
  • "sourceable_id": 12,
  • "sourceable_type": "HPE\Domain\Intermediation\Intermediaries\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",
  • "job": "Online Redakteur",
  • "employed_since": "2014-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": "2016