Introduction


Zigna 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 Jens Juul Nielsen (jjn@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 order

POST 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 kontakt
1 = Sælger SKAL kontaktes
2 = Hverken mægler eller sælger skal kontaktes

Packages

This method returns a list of available packages for order placement
GET 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 placement
GET 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 placement
GET 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.

Help / support

As our IT resources are limited, we cannot provide support in implementing your solution, but if you have questions regarding the API, please contact Jens Juul Nielsen (jjn@zigna.dk)