API: Contact

Owned by Shaon Karim (Unlicensed)
Last updated: Okt. 10, 2024 by Maciej Szewczyk
8 min read

Contact list

Notice: If contact login is type of sharer contact list will be reduced to contacts that have sharer= contact login (contact) - else list is reduced to contact contact login has access to.

JWT Authorisation

GET /api/v3/contact

Request parameter:

No Request parameter

Extra fields:

ParameterTypeINExampleDescription
has_mandate_filebooleanQUERYadd[has_mandate_file]=trueAllow displaying has_mandate_file field (indicator if contact has active mandate File in file_manger)
policy_countbooleanQUERYadd[policy_count]=trueAllow displaying count of not deleted policies (with archived)
permission_countbooleanQUERYadd[permission_count]=trueAllow displaying count of contact permisisons (from contact login)

/wiki/spaces/BROK/pages/693181 #Fields

Filtering parameters:

ParameterTypeINExampleDescription
search_termstringQUERYfilters[search_term]=AlpsFiltering by contact properties %search_term% in fields:
  • Company / Last Name
  • Additional / First name
  • E-mail
  • City
  • Web Page
  • Contact no.
  • Private E-Mail
  • Telephone store
  • Direct phone
  • Home phone
  • Mobile Phone
  • ZIP CODE

permission

intQUERYfilters[permission]=1

  • 0/null: all contacts

  • 1: only subcontacts → contact_login->contactPermissions

  • 2: only sharer contacts → contact->sharer


API: _ Default behavior#List defaults

Response data:

Metadata: object.

ParameterTypeDescription
countintNumber of all results marching criteria 
statusintResponse status (same as in http code)

Data:  object.data[array]

ParameterTypeDescription
idintegerContact id
nrstringContact nr 
namestringContact name (virtual field) - made from name_1 and name_2 
name_1stringContact first name (or company name)
name_2string|nullContact last name (or company addiction)
unique_idstringContact unique id

Response (Error):

ParameterTypeDescription
codeintegerAn error code
errorstringA message containing some information about the error 
errorsarrayList of errors devided by field in associative array {field_name:error message}

API: _ Default behavior#Authentication defaults 

Request
curl -X GET https://public.brokerstar.biz/api/v3/contact --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTg[...]cm5hbWUiOiJkZW1vLWRlIn0.VTVp[...]cqIg'


Response (Success)
200 OK 

    "count": "3",
    "data": [
        {
            "id": 17556,
			"nr": "01231",
            "name": "7 Alps Bio GmbH ",
            "name_1": "7 Alps Bio GmbH",
            "name_2": "",
			"unique_id": "950f6819a1f0e7f779d0089546fdfa98"
        },
        {
            "id": 16448,
			"nr": "01232",
            "name": "Martin Testuser",
            "name_1": "Martin",
            "name_2": "Testuser",
			"unique_id": "371b9c88a98e7880eef2431e8d61310d"
        },
		[...]
    ],
    "status": 200
}

Or one of 

Single Contact

Notice: If contact login is type of sharer contact list will be reduced to contacts that have sharer= contact login (contact) - else list is reduced to contact contact login has access to.

JWT Authorisation

GET /api/v3/contact/{id}

Request parameter:

ParameterTypeInDescription
idinturlid of requested contact

Response data:

Metadata: object.

ParameterTypeDescription
statusintResponse status (same as in http code)

Data:  object.data

ParameterOut TypeIn TypeDescription
idinteger
Contact id
nrstring
Contact nr
name_1stringstring(255)|nullLastname / Company name of the user
name_2string|nullstring(255)|nullFirstname / Company addition of the user Required if contact type=2
namestring
Contact name (virtual field) - made from name_1 and name_2 
post_codestring|nullstring(30)|nullContact post code
phone_workstring|nullstring(100)|nullPhone to work
mobilestring|nullstring(100)|nullPhone (mobile)
mailstring|nullstring(255)|nullEmail
mandate_beginstring(date)|nullstring(date)|nullMandate/Contract begin date
phone_directstring|nullstring(100)|nullPhone direct
phone_privatestring|nullstring(100)|nullProne private
mail_privatestring|nullstring(255)|nullEmail private
birthdaystring|nullstring(date)|nullContact birth day
security_numberstring|nullstring(30)|nullSocial security number
marital_statusarrayint|nullA array containing contact martial status information
marital_status[id]int|null
Martial status id
marital_status[name]string
Martial status name in language DE
marital_status[name_e]string|null
Martial status name in language EN
marital_status[name_i]string|null
Martial status name in language IT
marital_status[name_f]string|null
Martial status name in language FR
nationalityarrayint|nullA array containing nationality information
nationality[id]int|null
Country id
nationality[name]string
Country name in language DE
nationality[name_e]string|null
Country name in language EN
nationality[name_i]string|null
Country name in language IT
nationality[name_f]string|null
Country name in language FR
contact_typearrayint|nullA array containing contact type information
contact_type[id]integer
1=Company / 2=Person
contact_type[name]string
Contact type name in language DE
contact_type[name_e]string|null
Contact type name in language EN
contact_type[name_i]string|null
Contact type name in language IT
contact_type[name_f]string|null
Contact type name in language FR
addressstring|nullstring(255)|nullContact address
citystring|nullstring(50)|nullContact city
cantonarrayint|nullA array containing canton information
canton[id]int|null
Canton id
canton[name]string
Canton name in language DE
canton[name_e]string|null
Canton name in language EN
canton[name_i]string|null
Canton name in language IT
canton[name_f]string|null
Canton name in language FR
canton[name_short]string|null
Canton short name
countryarrayint|nullA array containing country information
country[id]int|null
Country id
country[name]string
Country name in language DE
country[name_e]string|null
Country name in language EN
country[name_i]string|null
Country name in language IT
country[name_f]string|null
Country name in language FR
languagearrayint|nullA array containing language information  (this field is used to determine interface language for contact)
language[id]int|null
API: Language id
language[locale]string(2)
Language locale
language[name]string
Language name in language DE
language[name_e]string|null
Language name in language EN
language[name_i]string|null
Language name in language IT
language[name_f]string|null
Language name in language FR
external_consultantsarray of arraysarray|string(1,2,3,4..)|nullAn array containing external consultant data API: Contact type
external_consultants[][id]int|null
External consultant id
permissionsarray|null
Permissions assigned to this contact (contact_login) info
permissions[id]int|null
Permission id
permissions[active]boolean|null
Is login avctive
permissions[mail]string|null
Permission related email
external_consultants[][name]string(200)
External consultant full name
unique_idstring
Unique ID of contact
has_mandate_fileboolean
Indicates if contact has active mandate File
policy_countint
Return count of undeleted policies
permission_countint
Return count of contact  contact login permission count

Response (Error):

ParameterTypeDescription
codeintegerAn error code
errorstringA message containing some information about the error 
errorsarrayList of errors devided by field in associative array {field_name:error message}
Request
curl -X GET https://public.brokerstar.biz/api/v3/contact/16448 --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTg[...]cm5hbWUiOiJkZW1vLWRlIn0.VTVp[...]cqIg'


Response (Success)
200 OK  
{
    "data": {
        "id": 16448,
		"nr": "00123",
        "name_1": "Martin",
        "name_2": "Testuser",
        "name": "Martin Testuser",
        "post_code": "8048",
        "phone_work": "+41614832101",
        "mobile": "+41614832104",
        "mail": "email@testuser.ch",
        "mandate_begin": "2022-08-10T00:00:00+02:00",
        "phone_direct": "+41614832102",
        "phone_private": "+41614832103",
        "mail_private": "private_email@testuser.ch",
        "birthday": "2001-08-10T00:00:00+02:00",
        "security_number": "123121-12312-12231",          
		"marital_status": {
            "name_e": "Married",
            "name_f": "Marié",
            "name_i": "Sposato",
            "id": 3,
            "name": "Verheiratet"
        },
        "nationality": {
            "name_e": "Australia",
            "name_f": "Australie",
            "name_i": "Australia",
            "id": 25,
            "name": "Australien"
        },
        "contact_type": {
            "name_e": "Person",
            "name_f": "Personne",
            "name_i": "Persona",
            "id": 2,
            "name": "Person"
        },
 		 "permissions": {
            "active": true,
            "mail": "somemail@wmc.ch",
            "id": 241
        },
 		"language": {
            "name_e": "German",
            "name_f": "allemand",
            "name_i": "tedesco",
            "id": 1,
            "locale": "de",
            "name": "Deutsch"
        },    
		 "external_consultants": [
            {
                "name": "WMC IT Solutions AG ",
                "id": 1
            },
            {
                "name": "WMC Hotline ",
                "id": 2
            }
        ],        
		"address": "Badenerstrasse 31b/12",
        "city": "Zürich",
        "fax": "+41614832105",
		"unique_id": "371b9c88a98e7880eef2431e8d61310d",
		"policy_count": 6,
        "sub_contact_count": 0
    },
    "status": 200
}
Response (Error)
404 Not found
{
	"error": "Entity not found",
	"code": 404
}
Response (Error)
403 Forbidden
{
	"error": "You have no access to contact id:123",
	"code": 403
}

Or one of 

Contact create

When creating new contact it will be automatically added to access permissions for the API: User creating this contact. Along the way the relation between the logged-in user and the created user will be created (see additional fields)

JWT Authorisation

POST /api/v3/contact

Request parameter:

ParameterTypeInDescription

JSON data (All fields beside name_1,name_2,contact_type,birthday  are optional and can be send selective):

ParameterOut TypeIn TypeDescription
All fields from Single Contact +
relation_creator_to_contactstring|nullstring|nullWhom is creator to created contact
relation_contact_to_creatorstring|nullstring|nullWhom is created contact to creator





Response data:

Request
curl -X POST https://public.brokerstar.biz/api/v3/contact -d '{
    "name_1": "Jon",
    "name_2": "Admin",
    "nationality": 2,
	"language":1
}'  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTg[...]cm5hbWUiOiJkZW1vLWRlIn0.VTVp[...]cqIg'
Response (Success)
200 OK   
{
	"status":200,
	"data": {
		"id": 1231
	}
}

Or one of 

Contact update


PUT /api/v3/contact/{id}

Request parameter:

ParameterTypeInDescription
idinturlOd of requested contact

JSON data (All fields are optional and can be send selective):

ParameterOut TypeIn TypeDescription
All fields from Single Contact +


Response data:

Request
curl -X PUT https://public.brokerstar.biz/api/v3/contact/16448 -d '{
    "plz": "9081",
    "mail": "new-email@testuser.ch",
    "nationality": 2,
	"language":1
}'  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTg[...]cm5hbWUiOiJkZW1vLWRlIn0.VTVp[...]cqIg'
Response (Success)
200 OK   
{
	"status":200
}
Response (Error)
404 Not found
{
	"error": "Entity not found",
	"code": 404
}
Response (Error)
403 Forbidden
{
	"error": "You have no access to contact id:123",
	"code": 403
}

Or one of 

Get avatar file

JWT Authorisation

GET /api/v3/contact/avatar/{contact}

Request parameter:

Parameter

Type

IN

Description

contactintegerURLContact id for which we are requesting avatar file

Response data:

BINARY FILE RESPONSE


Response (Error):

Parameter

Type

Description

codeintegerAn error code
errorstringA message containing some information about the error 
errorsarrayList of errors devided by field in associative array {field_name:error message}
Request
curl -X GET https://public.brokerstar.biz/api/v3/contact/avatar/16448 --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTg[...]cm5hbWUiOiJkZW1vLWRlIn0.VTVp[...]cqIg'
Response (Success)
200 OK   
BINARY RESPONSE
Response (Error)
404 Not found
{
	"error": "Avatar file not found for contact id: 123",
	"code": 404
}
Response (Error)
403 Forbidden
{
	"error": "You have no access to contact id:123",
	"code": 403
}

Or one of 

Get avatars

JWT Authorisation

GET /api/v3/contact/avatars

Request parameter:

Filtering parameters:

Parameter

Type

IN

Example

Description

contactstring|arrayQUERYfilters[contact]=4,34
or
filters[contact][]=4&filters[contact][]=34

Filtering by contact id IN value
if not set
Will return all allowed contacts avatars 

Response data:

Metadata: object.

Parameter

Type

Description

countintNumber of all results marching criteria 
statusintResponse status (same as in http code)

Data:  object.data[array]

Parameter

Type

Description

idintegerContact id
avatarstring|nullbase64 encoded image

Response (Error):

Parameter

Type

Description

codeintegerAn error code
errorstringA message containing some information about the error 
errorsarrayList of errors devided by field in associative array {field_name:error message}
Request
curl -X GET https://public.brokerstar.biz/api/v3/contact/avatars?filters[contact]=4,32 --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTg[...]cm5hbWUiOiJkZW1vLWRlIn0.VTVp[...]cqIg'
Response (Success)
200 OK 
{
    "count": 2,
    "data": [
        {
            "id": "4",
            "avatar": "data:image/gif;base64,iVBORw0KGgo....kSuQmCC"
        },
        {
            "id": "32",
            "avatar": null
        }
    ],
    "status": 200
}
Response (Error)
403 Forbidden
{
	"error": "You have no access to contact id:123",
	"code": 403
}

Or one of