A collection of help pages for using the API.
The API consists of a number of resources where each resource has an URL and a number of methods. A resource can, for example, be fiscal year. The URL would be like this:
https://web.foretagsplatsen.se/Api/v2/Company/{companyId}/FiscalYear/{FiscalYearId}
The last parameter can be omitted in order to retrieve a list of all items in the category of the resource.
For example, the following request would fetch all fiscal years for a company:
https://web.foretagsplatsen.se/Api/v2/Company/a-testagency-667788-9900/FiscalYear/
And in order to fetch only a single fiscal year you would provide the id of that year.
https://web.foretagsplatsen.se/Api/v2/Company/a-testagency-667788-9900/FiscalYear/123456789abcdef
All requests to the API are standard HTTP requests using the verbs GET, POST, PUT or DELETE. Although, all resources are not necessarily supporting every verb. You will find details on which verbs that are supported for each resource on their documentation page.
The GET verb is used for getting and listing data. The last parameter can be omitted in order to retrieve a list of all items in the category of the resource.
For example, the following request would fetch a list of companies:
GET /Api/v2/Company/ HTTP/1.1
And in order to fetch only a single company you would provide the company's id
GET /Api/v2/Company/a-testagency-667788-9900 HTTP/1.1
The DELETE verb is used for deleting data. The last parameter, specifies the id of the element that is being deleted. You can not delete all elements in a resource by omitting the id.
The following request would delete company 556898-6787
DELETE /Api/v2/Company/a-testagency-556898-6787 HTTP/1.1
The POST verb is used to create new data. An error will occur if there already exists a request is trying to create an object that already exists in the database (determined by collision of its unique id).
A POST request should specify the payload data in the body of the request. The URL parameters that are needed are specified in the documentation of each resource.
POST /Api/v2/Company/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: OAuth...
{
"businessIdentityCode": "556898-6787",
"name": "Demo company",
�
The PUT verb is used in order to update existing data. The characteristics of the action is essentially like the POST verb where you shall provide the payload data in the body of the request. The URL parameters that are needed are specified in the documentation of each resource.
PUT /Api/v2/Company/a-testagency-667788-9900 HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: OAuth...
{
"businessIdentityCode": "556898-6787",
"name": "Test company",
�
Each resource is normally receiving and returning data objects on the same form. The only thing that might differ is that some objects should not specify an id with the POST action. For example, document file and folder are objects that are being assigned an auto generated id when they are being stored in the database. Other objects such as agency are naturally given an id by the client that is creating them. These are details that are specified on each object's documentation page.
The data object in a PUT request does not need to be a complete object. It is only necessary to include fields that has changed. Unchanged data fields that are being omitted
remain unchanged on the server. Set property value to null in order to delete the existing value of that property.
Many resources requires a company id, which is a uniqe identifier in our system.
To get hold of the id for a company we recommend you to do a request to the Company resource (or similar) to get a list of all your companies with corresponding id's
It is possible to construct the id directly if the company is connected to an agency. The company id will then have the format:
a-{agencyId}-{businessIdentityCode}
So if you have an agency with the id "demo" and a company with business identity code "123456-1234", the id will look like:
a-demo-123456-1234
JSON is a compact, text based format for exchange of data and is specified by RFC 4627. The standard contains support for the datatypes: object, array, string and boolean. F�retagsplatsen is using a number of conventions from the Json.NET library in order to support more data types and details that is not included in the basic standard.
Dates are declared as a string according to ISO 8601 standard, which is on the format
YYYY-MM-DDThh:mm:ss if it is an UTC timestamp (e.g. 2012-12-31T23:59:59). Local timestamps has
also an timezone offset in hours and minutes (e.g. 2012-12-31T23:59:59+01:00).
A list in JSON is simply constructed by the classic array syntax [value1, value2, ... , valueN]. Any data type in JSON can be in a list, including objects and other lists.
When a request to the API is returning more than one result it is often the case that the result is a list of objects.
Numbers are treated according to the JSON standard with addition for Infinity and NaN.
JSON data
{
"a": -Infinity,
"b": Infinity,
"c": NaN,
"d": 123.3,
"e": 11,
"f": null,
}
Which would have the following interpretation in C#
float a = float.NegativeInfinity float b = float.PositiveInfinity float c = float.NaN float d = 123.3 float e = 11 float f -> Exception
Successful request.
The request contains invalid parameters or data.
The user needs to authenticate. See documentation for the different authentication methods that F�retagsplatsen is providing.
The requested object or resource does not exist.
The element already exists.
The operation could not be completed, because it is violating a rule of the resource.
An unexpected error has occured.
All HTTP status codes except HTTP 200 returns a JSON object with error description. For example something like the following object.
{
�typeOfError" : "NotFound",
�message" : "Company 'a-testagency-667788-9900' not found",
�identifier" : "B678F083-D95E-4E11-9DF2-C1B9C71C40B8"
}
N.B. It is possible that the webserver, a proxy or other node between the client and server returns the same HTTP status codes, although without the object.