InStaff Logo (Druckversion)

API / Programmier-Schnittstelle von InStaff

Restful API: Schnittstelle über die Sie Einsätze, Jobs, Platzierungen und Personalprofile abfragen können

InStaff ist eine Plattform über die Sie als Arbeitgeber schnell und einfach Personal für kurzfristige Minijobs buchen können. Dabei können Sie die gesamte Personalplanung sowie Personalbuchung online über Ihren InStaff Account durchführen. Wir stellen Kunden zusätzliche diese Programmier-Schnittstelle (Restful API) bereit, falls Sie die Daten der Personaleinsätze und Personalprofile in Ihr eigenes System importieren möchten.

Die Dokumentation richtet sich an Software Entwickler und ist nur in Englisch verfügbar. Sie können aber jederzeit einen E-Mail an unseren Entwickler senden und er beantwortet Ihnen alle Fragen persönlich: pascal.klein@instaff.jobs

General information


You can only access the API via HTTPS and all requests have to use this base URL to the current api version:

https://www.instaff.jobs/api/v1/

Every request must contain your API key as a query parameter:

	GET /api/v1/my_requested_ressource?apiKey=:apiKey HTTP/1.1
	Host: www.instaff.jobs

Replace the placeholder :apiKey with your API key. You can generate a key in your InStaff account on this page: https://www.instaff.jobs/customer/profile/api

Anybody who knows your API key has access to your data, but you can destroy an existing key and create a new one at any time.

It is a readonly API as of now and only accepts HTTP GET requests where the GET query parameters are in lower camelCase. It returns all data in JSON format (pretty printed) where the JSON properties are in lower camelCase.

Query your managers


You can access your InStaff account with more than one user. Each user is called a "manager" (in opposition to staff profiles who are also users of InStaff but who are called "staff"). Each manager has a unique email address.

You can retrieve an array with all managers of your account (ordered ascending by Id) via the following url to receive a response like below:

	https://www.instaff.jobs/api/v1/managers?apiKey=:apiKey
[
	{
		"id": 23,
		"lastname": "M\u00fcller",
		"email": "mueller@example.com"
	},
	{
		"id": 36,
		"lastname": "Schneider",
		"email": "schneider@example.com"
	},
	{
		"id": 37,
		"lastname": "Schneider",
		"email": "schneider2@examplde.com"
	}
]

You can retrieve a single manager by appending the id. This will return the single manager object (without wrappint it into an array).

	https://www.instaff.jobs/api/v1/managers/36?apiKey=:apiKey
{
	"id": 36,
	"lastname": "Schneider",
	"email": "schneider@example.com"
}

There are no additional options to filter or order the managers.

Query your deployments


Deployments are the highest level objects to group the staffing requests in your account. They are called "Events" in English accounts and "Einsätze" in German accounts. Each deployment is owned by one manager of your account and contains a start date, an end date, a location as well as a name.

You can retrieve an array with all deployments of your account (ordered ascending by StartDate, EndDate and then Id) via the following url to receive a response like below:

	https://www.instaff.jobs/api/v1/deployments?apiKey=:apiKey
[
	{
		"id": 234,
		"managerId": 23,
		"name": "Wedding in Munich",
		"startDate": "2016-08-16",
		"endDate": "2016-08-16",
		"city": "M\u00fcnchen",
		"locationDetails": "",
		"pdfBriefingUrlDe": "https:\/\/www.instaff.jobs\/pdf\/kundenbriefing\/muster",
		"pdfBriefingUrlEn": "https:\/\/en.instaff.jobs\/pdf\/kundenbriefing\/muster"
	},
	{
		"id": 123,
		"name": "Promoterion Flyering",
		"managerId": 23,
		"startDate": "2016-08-16",
		"endDate": "2016-08-18",
		"city": "Berlin",
		"locationDetails": "Adlon Hotel, Unter den Linden 77, 10117 Berlin",
		"pdfBriefingUrlDe": "https:\/\/www.instaff.jobs\/pdf\/kundenbriefing\/muster",
		"pdfBriefingUrlEn": "https:\/\/en.instaff.jobs\/pdf\/kundenbriefing\/muster"
	}
	
]

You can access a single deployment by appending the id. This will just return the single deployment object (without wrapping it into an array).

	https://www.instaff.jobs/api/v1/deployments/123?apiKey=:apiKey

You can filter the deployments by status and or managerId.

	https://www.instaff.jobs/api/v1/deployments?apiKey=:apiKey&managerId=23 //filtered by managerId
	https://www.instaff.jobs/api/v1/deployments?apiKey=:apiKey&status=ongoing //filtered by status

If you pass the a value for the parameter "status", it needs to be one of the following three:

  • ongoing - A deployment which is not yet over. It can contain jobs that are currently running or the whole deployment might still be in a planning stage.
  • finished - A deployment where all jobs are over but it either awaits the confirmation of working hours or its payment.
  • archived - A deployment where all jobs are over, all hours have been confirmed and and the invoice has already been paid.

Query your jobs


Every deployment can have multiple jobs. A job contains work related information such as the jobdescription, planned working hours and the minimum staff requirements. A job is published to all appropriate staff profiles in our database and these profiles can apply for a job. A manager can then book one or more available staff profiles for each job. Each booking of a staff profile is saved via a placement object. There are special kinds of jobs whose type are "direct" and these jobs have not been published, but were directly offered to a specific staff profile.

You can retrieve an array with all jobs from a certain deployment (ordered ascending by StartDate, StartingTime, EndDate and then Id) via the following url to receive a response like below:

	https://www.instaff.jobs/api/v1/jobs?apiKey=:apiKey&deploymentId=234
[
	{
		"id": 15663,
		"deploymentId": 234
		"position": "Team leader",
		"type": "normal",
		"plannedWorkingTime": "first day from 8 am to 2 pm, second day till 3:15 pm",
		"plannedWorkingHours": 13.25,
		"startDate": "2016-08-16",
		"startTime": "08:00:00",
		"endDate": "2016-08-17"
	},
	{
		"id": 15664,
		"deploymentId": 234
		"position": "Promoter",
		"type": "normal",
		"plannedWorkingTime": "daily from 8 am to 2 pm",
		"plannedWorkingHours": 12,
		"startDate": "2016-08-16",
		"startTime": "08:00:00",
		"endDate": "2016-08-17"
	}
]

You can retrieve a single job by appending the id. This will just return the single job object (without wrapping it into an array).

	https://www.instaff.jobs/api/v1/jobs/36?apiKey=:apiKey

There are no additional options to filter or order the jobs and it is not possible to retrieve all jobs from your account (without filtering via deploymentId).

Query your placements


A placement represents a certain staff profile that is booked for a certain job. It contains the wage of the staff for this job and whether the staff already confirmed the working contract. After the job is finished it also contains the working hours as well as the rating for this job.

You can retrieve an array with all placements from a certain deployment or job (ordered ascending by StartDate, StartingTime, EndDate and then Id) via the following url to receive a response like below:

	https://www.instaff.jobs/api/v1/placements?apiKey=:apiKey&jobId=23 //filtered by jobId
	https://www.instaff.jobs/api/v1/deployments?apiKey=:apiKey&deploymentId=23 //filtered by deploymentId
[
	{
		"id": 77771,
		"jobId":15664,
		"staffId": 14807,
		"contract": "confirmed",
		"workingHours": 7
	},
	{
		"id": 77772,
		"jobId": 15665,
		"staffId": 5555,
		"contract": "confirmed",
		"workingHours": 7.5
	}
]

As of now you can not retrieve a single placement.

You can filter placements by whether or not the staff already confirmed the working contract:

	https://www.instaff.jobsapi/v1/deployments?apiKey=:apiKey&deploymentId=23&contract=confirmed //filtered by contract confirmation

If you pass a value for the parameter "contract", it needs to be one of the following two:

  • confirmed - A placement where the staff already confirmed the working contract
  • notConfirmed - A placement where staff has not yet confirmed the working contract

Keep in mind that the staff has only limited time to confirm the working contract (maximum of 24 hours). If that time passed the placement gets deleted and does not exist anymore.

Query your staff


Every jobber who signs up on InStaff has a staff profile which contains information such as email, phone, profile image, gender and many more. You can only access staff profiles which you have booked and only specific information (e.g.: the staff give us their bank account and social security number, which you cannot access). In addition to profile information, we also list you how many times this person worked for you and any private comments you made.

As of now you can only retrieve a single staff profile by using the following url:

	https://www.instaff.jobs/api/v1/staff/5555?apiKey=:apiKey
{
	"id": 5555,
	"firstname": "Lisa",
	"lastname": "Schneider",
	"email": "lisa.schneider@exampl.de",
	"phone": "+491781234567",
	"birthDate": "1988-12-30",
	"profileLink": "https:\/\/www.instaff.jobs\/hostessen\/sedcard\/lisa-1234\erjdhladskjfnlafnl",
	"profileImage": "https:\/\/www.instaff.jobs\/files\/images\/erjdhladskjfnlafnl.jpg",
	"profileImageSmall": "https:\/\/www.instaff.jobs\/files\/images\/erjdhladskjfnlafnl.jpg",
	"numWorkedForYou": 6,
	"privateNoteFromYou": "Book her again for promotion team leads"
}

There are no additional options and now way to retreive an array of staff profiles.

Error handling


If you made an invalid request, the API will not respond with a HTTP 200 but instead with HTTP 400 Bad Request.

	HTTP/1.1 400 Bad Request

The API will return a json encoded error message and tries to give information about what went wrong and how to solve this issue.

{
  	"errorMessage": "Something went wrong: Please try the following to solve this issue!"
}