Introduction
Please note! The API is still in BETA - changes may occur without prior information. Not all methods are currently available, but the documentation will be updated when these methods are onlineZigna API is based on REST principles. You can use any HTTP client to communicate with the API.
The base URL for the API is https://api.zigna.dk/v2
The primary ways of communication between you and the API happens in JSON. A couple of the endpoints returns image data and zip data instead. This is described later in this documentation. You can use the HTTP verbs GET and POST to READ and CREATE objects in zigna's systems. The API is primarily focused on delivering Orders and Pictures to you. It is possible to create an Order, but this is the only place, at POST request is allowed. Everywhere else is only allowing GET requests.
Authentication
To authenticate yourself and to get access to your data, you must obtain an API key. You need to send an email to Jesper Lundsgaard Hansen (jlh@zigna.dk) in order to obtain the key. Please send your contact details, a description of what you intend to do and also which realtor you represent.
Important: The API key must remain secret. You shouldn't share it with anybody, as it grants access to your account. Keep it safe like your normal password.
The API key is sent with requests using X-headers. All requests must contain a X-ApiKey header value. The API key is a standard GUID object.
All requests must be sent over HTTPS. Requests sent over HTTP will be rejected.
Rate limiting
As the API is still in BETA the rate limiting is not switched on. The API is going to use rate limiting. This means that API key is allowed to send 2,000 API calls each day when enabled.
All requests sent after the limit is reached will be rejected until the next day, where the limit is reset.
Your current usage will be displayed in the following three HTTP response headers:
X-RateLimit-Limit: Tells you what your daily limit is.
X-RateLimit-Remaining: Tells you how many API calls you have left today.
X-RateLimit-Reset: Tells you how many seconds until your limit will be reset.
As of now these headers are excluded from the response. We will let you know when the rate limiting is enabled.
Errors
The API uses standard HTTP status code in responses. All successful requests are return with status code 2xx and errors are either returned as 4xx or 5xx. 4xx means that something is wrong with your request and 5xx means, that something is wrong on our site. All errors are logged in our system in order to help solving problems.
The API does not return any help messages right now. We're thinking of implementing this at a later time, if there is a need for it.
Endpoints
Orders
List all orders
This method returns all orders ordered by creation date ascending. Since the realtor can have very many orders, there's a limit of max 50 orders returned per request. You can page the resultset using the optional parameters TAKE and SKIP.TAKE is the limit - default/max: 50 items.
SKIP skips x number of order items and returns the orders after SKIP position in resultset.
Next is the url to the logical next orders in the resultset. Use this to iterate over all orders.
GET https://api.zigna.dk/v2/orders?take={take}&skip={skip}
Response
{
"response": {
"take": 50,
"skip": 0,
"next": "/v2/orders?take=50&skip=50"
},
"orders": [
{
"floors": integer,
"created": "yyyy-MM-ddTHH:mm:ss",
"picturesTakenDate": "yyyy-MM-ddTHH:mm:ss",
...
},
{
"floors": integer,
"created": "yyyy-MM-ddTHH:mm:ss",
"picturesTakenDate": "yyyy-MM-ddTHH:mm:ss",
...
},
]
}
Get specific order
This method returns a specific order. The {orderID} is the zigna ID of the order. This means you cannot query using the casenumber.GET https://api.zigna.dk/v2/orders/{orderID}
Response
{
"floors": integer,
"created": "yyyy-MM-ddTHH:mm:ss",
"picturesTakenDate": "yyyy-MM-ddTHH:mm:ss",
"status": "string",
"statusID": int
"totalPrice": decimal,
"products": {
"packageName": "string",
"packageProducts": [
"string",
"string"
],
"extraProducts": []
},
"photographer": {
"name": "string",
"phone": "string"
},
"finishedDate": "yyyy-MM-ddTHH:mm:ss",
"realtorWishes": string,
"id": string,
"caseNumber": string,
"m2": integer,
"seller": {
"name": string,
"address1": string,
"address2": string,
"postalCode": string,
"city": string,
"phone1": string,
"phone2": string,
"email": "string
},
"homeType": string,
"bookedDate": "yyyy-MM-ddTHH:mm:ss",
"isUrgent": boolean
}
Order states:
| Status ID | Status name |
|---|---|
| 1 | New order |
| 2 | Booked |
| 4 | Photos uploaded for editing |
| 5 | Order is completed and photos are ready |
| 6 | Pending |
| 50 | Season update |
Pictures
List all pictures assigned to order
This method returns all pictures assigned to an order.GET https://api.zigna.dk/v2/orders/{orderID}/pictures
{
"order": {
order-object as described earlier
},
"pictures": [
{
"pictureID": integer,
"originalFileName": string,
"link": string,
"size": integer,
"width": integer,
"height": integer
},
{
"pictureID": integer,
"originalFileName": string,
"link": string,
"size": integer,
"width": integer,
"height": integer
},
...
Download specific picture
This method downloads an image from the order.GET https://api.zigna.dk/v2/orders/{orderID}/pictures/{pictureID}
Response:
The response is of mimetype image/jpeg primarily. The mime type can also be pdf/swf.
Download all pictures
This method downloads all pictures assigned to the order.GET https://api.zigna.dk/v2/orders/{orderID}/pictures/zip
Response:
200 - success with a zipped response body
204 - no images was found
5xx - something wrong happened on the server
Upload picture
This method uploads a new picture to the order. The picture is placed as the last picture.POST https://api.zigna.dk/v2/orders/{orderID}/pictures
Response:
200 - success
Replace existing picture
This method replaces an existing picture based on our pictureID.POST https://api.zigna.dk/v2/orders/{orderID}/pictures/{pictureID}
Response:
200 - success
Create order
Use this method to create a new orderPOST https://api.zigna.dk/v2/orders
{
"floors": integer,
"created": "yyyy-MM-ddTHH:mm:ss",
"products": {
"packageName": "string", - see section "Packages"
"extraProducts": [ "string", "string"... ] - see section "Extra Products"
},
"realtorWishes": string,
"caseNumber": string,
"contactForm": integer, (see section "Contact Form"
"m2": integer,
"seller": {
"name": string,
"address1": string,
"address2": string,
"postalCode": string,
"city": string,
"phone1": string,
"phone2": string,
"email": "string
},
"homeType": integer, - see section "Home Types"
"isUrgent": boolean
}
Response:
200 - success
{
"status": "OK",
"orderNumber": string,
"created": "yyyy-MM-ddTHH:mm:ss"
}
Errors
The method will return the message "The order request does not match the required format. Please check https://api.zigna.dk under section "Create order" in all cases, where the format is wrong. Otherwise the order will be created and you'll get a 200 response back.
Contact Form
These contact forms are valid for order placement:0 = Nøglen fås af mægler uden sælger kontakt1 = Sælger SKAL kontaktes2 = Hverken mægler eller sælger skal kontaktes
Packages
This method returns a list of available packages for order placementGET https://api.zigna.dk/v2/orders/packages
Response:
[
{
"id": string,
"name": string,
"extraProducts": [
{
"id": string,
"name": string,
"description": string
},
{
"id": string,
"name": string,
"description": string
},
....
]
Use the id of the package in the order placement method under products -> packageName.This method also returns the products connected with the package. You don't need to send the extra products, that's already included in the package in the order request. If you do, we will remove them, as they are a part of the package.
Housing Types
This method returns a list of available housing types for order placementGET https://api.zigna.dk/v2/orders/housingtypes
Response:
[
{
"id": integer,
"name": string
},
{
"id": integer,
"name": string
},
....
]
Use the id field in order placement under homeType.
Extra Products
This method returns a list of available extra products for order placementGET https://api.zigna.dk/v2/orders/extraproducts
Response:
[
{
"id": string,
"name": string,
"description": string
},
{
"id": string,
"name": string,
"description": string
},
...
]
Use the id field in order placement under extraproducts.