# 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 ](https://docs.openprovider.com)as your reference.*

## <span>Searching for a handle  
</span>![Entering Geo Fence icon](https://openprovider.help/uploads/images/gallery/2026-08/embedded-image-rzlx3esx.png)<span>Use the endpoint path below. Base URL is determined by both the target environment and the API version.</span>

<div id="bkmrk-get-%7Bbase_url%7D%2Fcusto">```
<span><strong>GET</strong> <a href="http://docs.openprovider.com/#operation/"><strong>{base_url}</strong></a>/customer<br></br></span>
```

</div><span>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.</span>

<div id="bkmrk-request-values-name-"><details><summary>REQUEST VALUES</summary>

<table><tbody><tr><td>**<span>Name</span>**</td><td>**<span>Type</span>**</td><td>**<span>Description</span>**</td></tr><tr><td><span>handle\_pattern</span></td><td>string</td><td>Full or partial handle name. Wildcard (\*) can be used.</td></tr><tr><td>email\_pattern</td><td>string</td><td>Full or partial email address. Wildcard (\*) can be used.</td></tr><tr><td><span>first\_name\_pattern</span></td><td>string</td><td>Full or partial first name. Wildcard (\*) can be used.</td></tr><tr><td>last\_name\_pattern</td><td>string</td><td>Full or partial last name. Wildcard (\*) can be used.</td></tr><tr><td>company\_name\_pattern</td><td>string</td><td>Full or partial company name. Wildcard (\*) can be used.</td></tr><tr><td><span>comment\_pattern</span></td><td>string</td><td>Full or partial comment value. Wildcard (\*) can be used.</td></tr><tr><td>with\_additional\_data</td><td>boolean</td><td><span>Accepted values ‘true’ or ‘false’ - default value ‘false’</span></td></tr><tr><td>limit</td><td>integer</td><td>default value: 100, maximum value: 1000</td></tr><tr><td>offset</td><td>integer</td><td>default value: 0</td></tr></tbody></table>

</details><div id="bkmrk-request-examplecurl-"><div><details><summary>REQUEST EXAMPLE</summary>

```
<span>curl -X GET \ <br></br>'https://api.openprovider.eu/v1beta/customers?handle_pattern=XX123456-XX&with_additional_data=true' \ <br></br>-H 'Authorization: ,Bearer 2831a37fb8*******90b5aac822' \</span>
```

</details></div><details><summary>RESPONSE VALUES</summary>

<table><tbody><tr><td>**<span>Name</span>**</td><td>**<span>Type</span>**</td><td>**<span>Description</span>**</td></tr><tr><td>handle</td><td>varchar</td><td><span>Customer unique identifier or handle</span></td></tr><tr><td>company\_name</td></tr><tr><td>name</td></tr><tr><td>address</td></tr><tr><td>phone</td></tr><tr><td>fax</td></tr><tr><td>email</td></tr><tr><td>additional\_data</td><td>if withAdditionalData = true</td></tr><tr><td>extension\_additional\_data</td><td>if withAdditionalData = true</td></tr></tbody></table>

</details><details><summary>RESPONSE EXAMPLE</summary>

```
{<br></br> "code": 0,<br></br> "data": {<br></br> "results": [<br></br> {<br></br> "additional_data": {<br></br> "birth_address": "test street 45",<br></br> "birth_city": "Test city",<br></br> "birth_country": "NL",<br></br> "birth_date": "1970-01-01",<br></br> "birth_state": "Testprovince",<br></br> "birth_zipcode": "0123",<br></br> "cif_nif_number": "",<br></br> "company_registration_city": "Testcity",<br></br> "company_registration_number": "12345678",<br></br> "company_registration_subscription_date": "2000-01-01",<br></br> "cost_category": "",<br></br> "cost_center": "",<br></br> "headquarters_address": "Test street 5",<br></br> "headquarters_city": "Testcity",<br></br> "headquarters_country": "NL",<br></br> "headquarters_state": "Testprovince",<br></br> "headquarters_zipcode": "0123",<br></br> "internal_reference": "",<br></br> "passport_number": "0123456",<br></br> "project_code": "",<br></br> "purchase_order_number": "",<br></br> "social_security_number": "6543210"<br></br> },<br></br> "address": {<br></br> "city": "Test city",<br></br> "country": "NL",<br></br> "number": "1",<br></br> "state": "Testprovince",<br></br> "street": "Test street",<br></br> "suffix": "A",<br></br> "zipcode": "0123"<br></br> },<br></br> "comments": "",<br></br> "comments_last_changed_at": "",<br></br> "company_name": "",<br></br> "deleted_at": "0000-00-00 00:00:00",<br></br> "email": "test@mail.tld",<br></br> "email_verification_status": "FAI",<br></br> "extension_additional_data": [<br></br> {<br></br> "data": {<br></br> "admin_type": "1",<br></br> "applicant_purpose": "P3",<br></br> "birth_date": "1970-01-01",<br></br> "company_name_cyrillic": "Example company",<br></br> "company_name_latin": "Example company",<br></br> "company_registration_number": "XX123456789X11",<br></br> "contact_title": "CEO",<br></br> "ens_auth_id": "",<br></br> "ens_key": "",<br></br> "first_name_cyrillic": "Test",<br></br> "first_name_latin": "Test",<br></br> "hr_member": "",<br></br> "industry_class": "19",<br></br> "is_private_enterpreneur": "",<br></br> "last_name_cyrillic": "Person",<br></br> "last_name_latin": "Person",<br></br> "legal_address_cyrillic": "13245 Country, City, street, 2",<br></br> "middle_name_cyrillic": "Nikolaevich",<br></br> "middle_name_latin": "Nikolaevich",<br></br> "mobile_phone_number": "+7 (123) 456-78-90",<br></br> "nexus_category": "C31",<br></br> "org_type": "1",<br></br> "passport_issue_date": "2009-01-11",<br></br> "passport_issuer": "Issuer name",<br></br> "passport_number": "12345678",<br></br> "passport_series": "1234",<br></br> "postal_address_cyrillic": "12345 Country, City, street, 1",<br></br> "social_security_number": "X123455123X",<br></br> "tax_payer_number": "1345678",<br></br> "uin": "12345-6",<br></br> "user_type": "Individual",<br></br> "vat": "12345678",<br></br> "website": "http://example.com",<br></br> "whois_email": "test@mail.tld"<br></br> },<br></br> "name": "ru"<br></br> }<br></br> ],<br></br> "gender": "M",<br></br> "handle": "XX123456-XX",<br></br> "id": 12345,<br></br> "is_deleted": false,<br></br> "locale": "nl_NL",<br></br> "name": {<br></br> "first_name": "Test",<br></br> "full_name": "Test Person",<br></br> "initials": "T P",<br></br> "last_name": "Person",<br></br> "prefix": "van der"<br></br> },<br></br> "phone": {<br></br> "area_code": "10",<br></br> "country_code": "+01",<br></br> "subscriber_number": "123456"<br></br> },<br></br> "reseller_id": 5349,<br></br> "tags": [<br></br> {<br></br> "key": "customer",<br></br> "value": "VIP"<br></br> }<br></br> ]<br></br> }<br></br> ],<br></br> "total": 149<br></br> },<br></br> "desc": ""<br></br>}
```

</details></div>```
{<br></br>"code": 0,<br></br>"desc": "",<br></br>"data": {<br></br>"results": [<br></br>{<br></br>"id": 123456789,<br></br>"company_name": "<span>Example company</span>",<br></br>"name": {<br></br>"first_name": "<span>Test</span>",<br></br>"last_name": "<span>Person</span>",<br></br>"full_name": "Test Person"<br></br>},<br></br>"phone": {<br></br>"country_code": "<span>+03</span>",<br></br>"area_code": "<span>111</span>",<br></br>"subscriber_number": "123456"<br></br>},<br></br>"address": {<br></br>"street": "Test street",<br></br>"number": "123",<br></br>"zipcode": "1235 XX",<br></br>"city": "Rotterdam",<br></br>"country": "NL",<br></br>"state": "Test province"<br></br>},<br></br>"email": "test@mail.tld",<br></br>"handle": "XX123456-XX",<br></br>"reseller_id": 12345,<br></br>"locale": "en_001",<br></br>"deleted_at": "0000-00-00 00:00:00",<br></br>"is_deleted": false,<br></br>"email_verification_status": "ACT"<br></br>}<br></br>],<br></br>"total": 1<br></br>}<br></br>}
```

<div><details><summary>RESPONSE VALUES</summary>

<table><tbody><tr><td>**<span>Name</span>**</td><td>**<span>Type</span>**</td><td>**<span>Description</span>**</td></tr><tr><td>handle</td><td>varchar</td><td><span>Customer unique identifier or handle</span></td></tr><tr><td>company\_name</td></tr><tr><td>vat</td></tr><tr><td>name</td></tr><tr><td>address</td></tr><tr><td>phone</td></tr><tr><td>fax</td></tr><tr><td>email</td></tr><tr><td>additional\_data</td><td>if withAdditionalData = true</td></tr><tr><td>extension\_additional\_data</td><td>if withAdditionalData = true</td></tr></tbody></table>

</details>##   
Retrieving a handle

Once we know that a particular user handle exists, we can retrieve its data by calling Get Customer:

## ![Entering Geo Fence icon](https://openprovider.help/uploads/images/gallery/2026-08/embedded-image-7ig8yy8l.png)<span>Use the endpoint path below. Base URL is determined by both the target environment and the API version.</span>

<div><span>**GET** [**{base\_url}**](http://docs.openprovider.com/#operation/)/customer/{handle}  
</span></div><details><summary>REQUEST VALUES</summary>

<table><tbody><tr><td>**<span>Name</span>**</td><td>**<span>Type</span>**</td><td>**<span>Description</span>**</td></tr><tr><td>[handle](https://doc.openprovider.eu/API_Format_Handle)</td><td>string</td><td>Customer unique handle</td></tr><tr><td>with\_additional\_data</td><td>string</td><td><span>Accepted values ‘true’ or ‘false’ - default value ‘false’</span></td></tr></tbody></table>

</details><details><summary>REQUEST EXAMPLE</summary>

</details></div>```
<span>curl -X GET \ <br></br>'https://api.openprovider.eu/v1beta/customers/XX123456-XX?with_additional_data=true' \ <br></br>-H 'Authorization: ,Bearer 2831a37fb8*******90b5aac822' \<br></br></span>
```

<div><details><summary>RESPONSE VALUES</summary>

<table><tbody><tr><td>**<span>Name</span>**</td><td>**<span>Type</span>**</td><td>**<span>Description</span>**</td></tr><tr><td>handle</td><td>varchar</td><td><span>Customer unique identifier or handle</span></td></tr><tr><td>company\_name</td></tr><tr><td>vat</td></tr><tr><td>name</td></tr><tr><td>address</td></tr><tr><td>phone</td></tr><tr><td>fax</td></tr><tr><td>email</td></tr><tr><td>additional\_data</td><td>if withAdditionalData = true</td></tr><tr><td>extension\_additional\_data</td><td>if withAdditionalData = true</td></tr></tbody></table>

</details><details><summary>RESPONSE EXAMPLE</summary>

</details></div>```
{<br></br> "code": 0,<br></br> "desc": "",<br></br> "data": {<br></br> "additional_data": {<br></br> "birth_address": "test street 45",<br></br> "birth_city": "Test city",<br></br> "birth_country": "NL",<br></br> "birth_date": "1970-01-01",<br></br> "birth_state": "Testprovince",<br></br> "birth_zipcode": "0123",<br></br> "cif_nif_number": "",<br></br> "company_registration_city": "Testcity",<br></br> "company_registration_number": "12345678",<br></br> "company_registration_subscription_date": "2000-01-01",<br></br> "cost_category": "",<br></br> "cost_center": "",<br></br> "headquarters_address": "Test street 5",<br></br> "headquarters_city": "Testcity",<br></br> "headquarters_country": "NL",<br></br> "headquarters_state": "Testprovince",<br></br> "headquarters_zipcode": "0123",<br></br> "internal_reference": "",<br></br> "passport_number": "0123456",<br></br> "project_code": "",<br></br> "purchase_order_number": "",<br></br> "social_security_number": "6543210"<br></br> },<br></br> "address": {<br></br> "city": "Test city",<br></br> "country": "NL",<br></br> "number": "1",<br></br> "state": "Testprovince",<br></br> "street": "Test street",<br></br> "suffix": "A",<br></br> "zipcode": "0123"<br></br> },<br></br> "comments": "some comment here",<br></br> "comments_last_changed_at": "2014-05-08 19:04:11",<br></br> "company_name": "Example company",<br></br> "deleted_at": "0000-00-00 00:00:00",<br></br> "email": "test@mail.tld",<br></br> "email_verification_status": "ACT",<br></br> "extension_additional_data": [<br></br> {<br></br> "data": {<br></br> "admin_type": "1",<br></br> "applicant_purpose": "P3",<br></br> "birth_date": "1970-01-01",<br></br> "company_name_cyrillic": "Example company",<br></br> "company_name_latin": "Example company",<br></br> "company_registration_number": "XX123456789X11",<br></br> "contact_title": "CEO",<br></br> "ens_auth_id": "",<br></br> "ens_key": "",<br></br> "first_name_cyrillic": "Test",<br></br> "first_name_latin": "Test",<br></br> "hr_member": "",<br></br> "industry_class": "19",<br></br> "is_private_enterpreneur": "",<br></br> "last_name_cyrillic": "Person",<br></br> "last_name_latin": "Person",<br></br> "legal_address_cyrillic": "13245 Country, City, street, 2",<br></br> "middle_name_cyrillic": "Nikolaevich",<br></br> "middle_name_latin": "Nikolaevich",<br></br> "mobile_phone_number": "+7 (123) 456-78-90",<br></br> "nexus_category": "C31",<br></br> "org_type": "1",<br></br> "passport_issue_date": "2009-01-11",<br></br> "passport_issuer": "Issuer name",<br></br> "passport_number": "12345678",<br></br> "passport_series": "1234",<br></br> "postal_address_cyrillic": "12345 Country, City, street, 1",<br></br> "social_security_number": "X123455123X",<br></br> "tax_payer_number": "1345678",<br></br> "uin": "12345-6",<br></br> "user_type": "Individual",<br></br> "vat": "12345678",<br></br> "website": "http://example.com",<br></br> "whois_email": "test@mail.tld"<br></br> },<br></br> "name": "ru"<br></br> }<br></br> ],<br></br> "fax": {<br></br> "area_code": "001",<br></br> "country_code": "+01",<br></br> "subscriber_number": "123456"<br></br> },<br></br> "gender": "M",<br></br> "handle": "XX123456-XX",<br></br> "id": 5349,<br></br> "inn": "123456789",<br></br> "is_deleted": false,<br></br> "locale": "nl_NL",<br></br> "name": {<br></br> "first_name": "Test",<br></br> "full_name": "Test Person",<br></br> "initials": "T P",<br></br> "last_name": "Person",<br></br> "prefix": "van der"<br></br> },<br></br> "phone": {<br></br> "area_code": "10",<br></br> "country_code": "+01",<br></br> "subscriber_number": "123456"<br></br> },<br></br> "reseller_id": 5349,<br></br> "tags": [<br></br> {<br></br> "key": "customer",<br></br> "value": "VIP"<br></br> }<br></br> ],<br></br> "vat": "XX123456789X11"<br></br> },<br></br> "desc": ""<br></br>}
```

</div>