7 Customers API: How to get an existing handle

This is a series of articles dedicated to managing customer objects via Openprovider API.
This is a second article in a series in which we are going to cover customer handle search. To get more information about our API in general, please use our documentation portal as your reference.
Searching for a handle
Use the endpoint path below. Base URL is determined by both the target environment and the API version.
GET {base_url}/customer
Our API has two methods that can return information about an existing customer object. The first one that we are going to cover is a method that returns a list of customer objects matching particular search criteria.
REQUEST VALUES
Name
Type
Description
handle_pattern
string
Full or partial handle name. Wildcard (*) can be used.
email_pattern
string
Full or partial email address. Wildcard (*) can be used.
first_name_pattern
string
Full or partial first name. Wildcard (*) can be used.
last_name_pattern
string
Full or partial last name. Wildcard (*) can be used.
company_name_pattern
string
Full or partial company name. Wildcard (*) can be used.
comment_pattern
string
Full or partial comment value. Wildcard (*) can be used.
with_additional_data
boolean
Accepted values ‘true’ or ‘false’ - default value ‘false’
limit
integer
default value: 100, maximum value: 1000
offset
integer
default value: 0
REQUEST EXAMPLE
curl -X GET \ 
'https://api.openprovider.eu/v1beta/customers?handle_pattern=XX123456-XX&with_additional_data=true' \ 
-H 'Authorization: ,Bearer 2831a37fb8*******90b5aac822' \
RESPONSE VALUES
Name
Type
Description
handle
varchar
Customer unique identifier or handle
company_name
name
address
phone
fax
email
additional_data
if withAdditionalData = true
extension_additional_data
if withAdditionalData = true
RESPONSE EXAMPLE
{
 "code": 0,
 "data": {
 "results": [
 {
 "additional_data": {
 "birth_address": "test street 45",
 "birth_city": "Test city",
 "birth_country": "NL",
 "birth_date": "1970-01-01",
 "birth_state": "Testprovince",
 "birth_zipcode": "0123",
 "cif_nif_number": "",
 "company_registration_city": "Testcity",
 "company_registration_number": "12345678",
 "company_registration_subscription_date": "2000-01-01",
 "cost_category": "",
 "cost_center": "",
 "headquarters_address": "Test street 5",
 "headquarters_city": "Testcity",
 "headquarters_country": "NL",
 "headquarters_state": "Testprovince",
 "headquarters_zipcode": "0123",
 "internal_reference": "",
 "passport_number": "0123456",
 "project_code": "",
 "purchase_order_number": "",
 "social_security_number": "6543210"
 },
 "address": {
 "city": "Test city",
 "country": "NL",
 "number": "1",
 "state": "Testprovince",
 "street": "Test street",
 "suffix": "A",
 "zipcode": "0123"
 },
 "comments": "",
 "comments_last_changed_at": "",
 "company_name": "",
 "deleted_at": "0000-00-00 00:00:00",
 "email": "test@mail.tld",
 "email_verification_status": "FAI",
 "extension_additional_data": [
 {
 "data": {
 "admin_type": "1",
 "applicant_purpose": "P3",
 "birth_date": "1970-01-01",
 "company_name_cyrillic": "Example company",
 "company_name_latin": "Example company",
 "company_registration_number": "XX123456789X11",
 "contact_title": "CEO",
 "ens_auth_id": "",
 "ens_key": "",
 "first_name_cyrillic": "Test",
 "first_name_latin": "Test",
 "hr_member": "",
 "industry_class": "19",
 "is_private_enterpreneur": "",
 "last_name_cyrillic": "Person",
 "last_name_latin": "Person",
 "legal_address_cyrillic": "13245 Country, City, street, 2",
 "middle_name_cyrillic": "Nikolaevich",
 "middle_name_latin": "Nikolaevich",
 "mobile_phone_number": "+7 (123) 456-78-90",
 "nexus_category": "C31",
 "org_type": "1",
 "passport_issue_date": "2009-01-11",
 "passport_issuer": "Issuer name",
 "passport_number": "12345678",
 "passport_series": "1234",
 "postal_address_cyrillic": "12345 Country, City, street, 1",
 "social_security_number": "X123455123X",
 "tax_payer_number": "1345678",
 "uin": "12345-6",
 "user_type": "Individual",
 "vat": "12345678",
 "website": "http://example.com",
 "whois_email": "test@mail.tld"
 },
 "name": "ru"
 }
 ],
 "gender": "M",
 "handle": "XX123456-XX",
 "id": 12345,
 "is_deleted": false,
 "locale": "nl_NL",
 "name": {
 "first_name": "Test",
 "full_name": "Test Person",
 "initials": "T P",
 "last_name": "Person",
 "prefix": "van der"
 },
 "phone": {
 "area_code": "10",
 "country_code": "+01",
 "subscriber_number": "123456"
 },
 "reseller_id": 5349,
 "tags": [
 {
 "key": "customer",
 "value": "VIP"
 }
 ]
 }
 ],
 "total": 149
 },
 "desc": ""
}
{
"code": 0,
"desc": "",
"data": {
"results": [
{
"id": 123456789,
"company_name": "Example company",
"name": {
"first_name": "Test",
"last_name": "Person",
"full_name": "Test Person"
},
"phone": {
"country_code": "+03",
"area_code": "111",
"subscriber_number": "123456"
},
"address": {
"street": "Test street",
"number": "123",
"zipcode": "1235 XX",
"city": "Rotterdam",
"country": "NL",
"state": "Test province"
},
"email": "test@mail.tld",
"handle": "XX123456-XX",
"reseller_id": 12345,
"locale": "en_001",
"deleted_at": "0000-00-00 00:00:00",
"is_deleted": false,
"email_verification_status": "ACT"
}
],
"total": 1
}
}
RESPONSE VALUES
Name
Type
Description
handle
varchar
Customer unique identifier or handle
company_name
vat
name
address
phone
fax
email
additional_data
if withAdditionalData = true
extension_additional_data
if withAdditionalData = true
Retrieving a handle
Once we know that a particular user handle exists, we can retrieve its data by calling Get Customer:
Use the endpoint path below. Base URL is determined by both the target environment and the API version.
GET {base_url}/customer/{handle}
REQUEST VALUES
Name
Type
Description
handle
string
Customer unique handle
with_additional_data
string
Accepted values ‘true’ or ‘false’ - default value ‘false’
REQUEST EXAMPLE
curl -X GET \ 
'https://api.openprovider.eu/v1beta/customers/XX123456-XX?with_additional_data=true' \ 
-H 'Authorization: ,Bearer 2831a37fb8*******90b5aac822' \
RESPONSE VALUES
Name
Type
Description
handle
varchar
Customer unique identifier or handle
company_name
vat
name
address
phone
fax
email
additional_data
if withAdditionalData = true
extension_additional_data
if withAdditionalData = true
RESPONSE EXAMPLE
{
 "code": 0,
 "desc": "",
 "data": {
 "additional_data": {
 "birth_address": "test street 45",
 "birth_city": "Test city",
 "birth_country": "NL",
 "birth_date": "1970-01-01",
 "birth_state": "Testprovince",
 "birth_zipcode": "0123",
 "cif_nif_number": "",
 "company_registration_city": "Testcity",
 "company_registration_number": "12345678",
 "company_registration_subscription_date": "2000-01-01",
 "cost_category": "",
 "cost_center": "",
 "headquarters_address": "Test street 5",
 "headquarters_city": "Testcity",
 "headquarters_country": "NL",
 "headquarters_state": "Testprovince",
 "headquarters_zipcode": "0123",
 "internal_reference": "",
 "passport_number": "0123456",
 "project_code": "",
 "purchase_order_number": "",
 "social_security_number": "6543210"
 },
 "address": {
 "city": "Test city",
 "country": "NL",
 "number": "1",
 "state": "Testprovince",
 "street": "Test street",
 "suffix": "A",
 "zipcode": "0123"
 },
 "comments": "some comment here",
 "comments_last_changed_at": "2014-05-08 19:04:11",
 "company_name": "Example company",
 "deleted_at": "0000-00-00 00:00:00",
 "email": "test@mail.tld",
 "email_verification_status": "ACT",
 "extension_additional_data": [
 {
 "data": {
 "admin_type": "1",
 "applicant_purpose": "P3",
 "birth_date": "1970-01-01",
 "company_name_cyrillic": "Example company",
 "company_name_latin": "Example company",
 "company_registration_number": "XX123456789X11",
 "contact_title": "CEO",
 "ens_auth_id": "",
 "ens_key": "",
 "first_name_cyrillic": "Test",
 "first_name_latin": "Test",
 "hr_member": "",
 "industry_class": "19",
 "is_private_enterpreneur": "",
 "last_name_cyrillic": "Person",
 "last_name_latin": "Person",
 "legal_address_cyrillic": "13245 Country, City, street, 2",
 "middle_name_cyrillic": "Nikolaevich",
 "middle_name_latin": "Nikolaevich",
 "mobile_phone_number": "+7 (123) 456-78-90",
 "nexus_category": "C31",
 "org_type": "1",
 "passport_issue_date": "2009-01-11",
 "passport_issuer": "Issuer name",
 "passport_number": "12345678",
 "passport_series": "1234",
 "postal_address_cyrillic": "12345 Country, City, street, 1",
 "social_security_number": "X123455123X",
 "tax_payer_number": "1345678",
 "uin": "12345-6",
 "user_type": "Individual",
 "vat": "12345678",
 "website": "http://example.com",
 "whois_email": "test@mail.tld"
 },
 "name": "ru"
 }
 ],
 "fax": {
 "area_code": "001",
 "country_code": "+01",
 "subscriber_number": "123456"
 },
 "gender": "M",
 "handle": "XX123456-XX",
 "id": 5349,
 "inn": "123456789",
 "is_deleted": false,
 "locale": "nl_NL",
 "name": {
 "first_name": "Test",
 "full_name": "Test Person",
 "initials": "T P",
 "last_name": "Person",
 "prefix": "van der"
 },
 "phone": {
 "area_code": "10",
 "country_code": "+01",
 "subscriber_number": "123456"
 },
 "reseller_id": 5349,
 "tags": [
 {
 "key": "customer",
 "value": "VIP"
 }
 ],
 "vat": "XX123456789X11"
 },
 "desc": ""
}