API Reference

Getting Started with Worldbox API

This page will help you get started with Worldbox API. You'll be up and running in a jiffy!

Overview

The Worldbox application-programming interface (API) is a set of programming instructions and standards for accessing our worldwide company index and place orders and retrieve company reports, credit reports, financial data and legal documents.

The API is intended to return the requested company document in all available formats - including XML. The returned files are "embedded" as base64 encoded string the JSON response.

Get a test account

Please contact our account manager for the access to the test environment. Don’t hestiate to email us directly at [email protected] or call us at +41 44 391 34 31.

REST Architecture

The Worldbox webservice API is completely designed in within the REST architecture. REST is not a technology it’s rather an architectural style of exposing API to the web service consumers. An important concept in REST is the existence of resources (sources of specific information), each of which is referenced with a global identifier (e.g., a URI in HTTP).

For more information please go ahead to our dedicated page REST Webservice.

API Host

http://testapi.worldbox.ch (Development)
https://api.worldbox.ch (Production)

Authentication

Worldbox uses sessionless authentication. For each request an API Key and API Secret has to be included into the request-header. Think of username/password for authentication, but it’s not per person, it’s per API consumer.

Most client software provides a simple mechanism for supplying a user name and password and will build the required authentication headers automatically. For example you can specify the -u argument with curl as follows

curl -D- -u fred:fred -X GET -H "Content-Type: application/json" https://api.worldbox.ch/v1/companies/?q=worldbox&countrycode=CH

Supplying Basic Auth headers

If you need to you may construct and send basic auth headers yourself. To do this you need to perform the following steps:

  1. Build a string of the form apikey:apisecret
  2. Base64 encode the string
  3. Supply an "Authorization" header with content "Basic " followed by the encoded string,
    e.g. "Basic YWRtaW46YWRtaW4="
curl -D- -X GET -H "Authorization: Basic ZnJlZDpmcmVk" -H "Content-Type: application/json" https://api.worldbox.ch/v1/companies/?q=worldbox&countrycode=CH

Convention

  • Client - Client application.
  • Status - HTTP status code of response.
  • All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request server.
  • All response are in JSON format.
  • All request parameters are mandatory unless explicitly marked as [optional]