REST API Documentation

This interface uses the REST and JSON standards for communication.

Endpoint

https://api.zorgmail.nl/addressbook/v1/edi/

Authentication

HTTP Basic authentication is required, use your application or personal credentials.

Method

We only support GET requests.

Query string

?q={searchText}&start={startrow}&rows={rows-returned}

The value in bold must be replaced.

Query string parameters

Name Type Mandatory Possible values Description
q string Yes any search string
start int Yes 1,2,3,etc. The starting row number to be returned. Maximum allowed value is 2000.
rows int Yes 1,2,3,...,10,...,20,...,30,etc. Maximum Rows Returned. Maximum allowed value is 100.
fn string No canRelay You can use this parameter to test whether or not ZorgMail can use Safe Relay to a given recipient address. When the query has no results and the sender has delivery with the ZorgMail Viewer enabled, the email needs to contain the recipient’s phone number to enforce two-factor authentication in the ZorgMail Viewer.

Returns

Possible GET Response Status Codes include
Response code Description
200 OK The request was successful and the response body contains the representation requested.
400 BAD REQUEST The request is invalid. All query string parameters are mandatory. An unknown parameter is not accepted.
404 NOT FOUND We could not locate the resource based on the specified URI.
500 SERVER ERROR We could not return the representation due to an internal server error.
503 SERVICE UNAVAILABLE We are temporarily unable to service the request. Please wait for a bit and try again.
Attributes to return when response code is 200
Name Type Description
id string ZorgMail Mailbox id, also known as Customer number ('Klantnummer').
displayName string Summary of the mailbox profile, the identity of the addressee.
mailAddress string Default ZorgMail EDI address. EDI messages cannot be delivered for role='Domein'.
mailAddressEmail string Default ZorgMail Secure e-mail address. When this field is empty the user has no secure e-mailbox and can receive EDI only.
Replace 'veiligmailen_is_mogelijk_met_' with your addressee for role='Domein'.
role string Role of person or practice
zvAgbCode string AGB-practitioner code: pratitioner type N02 + practitioner number N06. Leading zero's added to fixed length.
gender string F/M/U/N. Gender: Female / Male / Unknown / None for non-person.
surname string For person, equal to the department or organization.
initials string Initials with punctuation.
prefix string Surname prefix.
department string Department in organization.
organizationId string Organization ID. Meaningless, can change in time.
prAgbCode string AGB-practice code: practice type N02 + practice number N06. Leading zero's added to fixed length.
organizationType string Organization type.
organization string Organization name.
street string Street.
houseNumber string House number and additions.
postalCode string Postal code.
locality string Locality or City.
country string Country name.
telephoneNumber string Telephone number of organization.

* Empty value fields will not be returned in the response.
* Only json object will be returned.

Example request and response (search recipient address)

Retrieving https://api.zorgmail.nl/addressbook/v1/edi/?q=vanad test huisartsenpraktijk&start=1&rows=1 would use the following HTTP Request:
GET addressbook/v1/edi/?q=vanad test huisartsenpraktijk&start=1&rows=1 HTTP/1.1
Host: api.zorgmail.nl
Authorization: Basic ******…
			
This address exists, so we return a '200 OK' status in the headers, and json encoded data in the response body:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8					 
    {
    "numFound": 2,
    "addresses": [
        {
            "id": "000091087",
            "displayName": "Huisartsenpraktijk Test 1 (VANAD Enovation Filetransfer 1)",
            "mailAddress": "000091087@lms.lifeline.nl",
            "role": "Huisartsenpraktijk",
            "zvAgbCode": "99007105",
            "gender": "U",
            "surname": "Huisartsenpraktijk Test 1 (ENOVATION Filetransfer 1)",
            "organizationId": "000091087",
            "prAgbCode": "99057105",
            "organizationType": "Testpraktijk",
            "organization": "ZorgMail Test",
            "street": "Rivium Westlaan",
            "houseNumber": "1",
            "postalCode": "2909 LD",
            "locality": "CAPELLE AAN DEN IJSSEL",
            "country": "NEDERLAND",
            "telephoneNumber": "010-2881600"
        }
    ]
    }
				

Example request and response (canRelay)

Retrieving https://api.zorgmail.nl/addressbook/v1/edi/?q=test@gmail.com&start=1&rows=20&fn=canRelay would use the following HTTP Request:
GET addressbook/v1/edi/?q=test@gmail.com&start=1&rows=20&fn=canRelay HTTP/1.1
Host: api.zorgmail.nl
Authorization: Basic ******…
            
When ZorgMail cannot use Safe Relay to a given recipient address (test@gmail.com), numFound in the response body is 0 with the return code '200 OK' in the headers:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8                    
    {
        "numFound": 0
    }
                

Example request and response (canRelay)

Retrieving https://api.zorgmail.nl/addressbook/v1/edi/?q=test@mcrd.nl&start=1&rows=20&fn=canRelay would use the following HTTP Request:
GET addressbook/v1/edi/?q=test@mcrd.nl&start=1&rows=20&fn=canRelay HTTP/1.1
Host: api.zorgmail.nl
Authorization: Basic ******…
            
When ZorgMail can use Safe Relay to a given recipient address (test@mcrd.nl), numFound in the response body is greater than 0 with the return code '200 OK' in the headers:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8                    
    {
    "numFound": 1,
    "addresses": [
        {
            "id": "500088155",
            "displayName": "Vanad Enovation Demo Domein",
            "mailAddress": "500088155@lms.lifeline.nl",
            "mailAddressEmail": "veiligmailen_is_mogelijk_met_@mcrd.nl",
            "role": "Domein",
            "gender": "U",
            "surname": "Vanad Enovation Demo Domein",
            "organizationId": "800040599",
            "prAgbCode": "99001234",
            "organization": "VANAD Enovation",
            "street": "Rivium Westlaan",
            "houseNumber": "1",
            "postalCode": "2909 LD",
            "locality": "CAPELLE AAN DEN IJSSEL",
            "country": "NEDERLAND",
            "telephoneNumber": "010-2881600"
        }
    ]
    }