Get started with the Procurios API

Welcome to the Procurios API! If you are reading this, then a client has given you access to their environment and asked you to build something that interacts with our software.

This documentation is designed to help you with that process, and we hope you will enjoy working with it! Should you find this documentation lacking, or have any other feedback for the Procurios team directly, there's a "Feedback" button in the top right corner.

Within this documentation environment, you will find information on all the various information you can retrieve from and send to our system, as well as tools to test the API itself and access to logs for any calls that have been made.

Who is Procurios?

Ever since Procurios was founded in 2001, we have been developing and improving our proprietary Procurios Platform, which we specifically build for associations and charity organisations.

Our main office is located in The Netherlands (Houten, UT) with a second office located in Belgium (Mechelen).

We see ourselves as a ‘challenging partner’, we value open communication and pride ourselves on being an involved partner more than just simply a supplier.

We work closely with our clients to help them formulate a solid online strategy, create a strong design both functionally and visually and provide them with the best resources to realize it all. We are always looking for ways to improve their conversion and engagement with their target audiences.

The client and the Procurios team.

While this API has been built on the Procurios platform, most of your communication will go through our shared client. They can manage your access to these documents, as well as manage your available permissions within the API itself.

The documentation automatically updates based on your current permissions, so if you are missing methods that you feel you need to build your application, check in with them for additional permissions!

Using this documentation

In the menu on the left, you will see a list of all the APIs you have access to. Each API will show a list of available methods. Each method shows the URL and the required arguments to call it, as well as an example of the output structure.

Each method also has a "live testing" option, which you can use to test the method directly from the browser. It is important to note that test calls will modify the environment they are used on.

Finally, each method also has a "logs" button, which you can use to access the logs for any calls to that specific method. This will include both calls made from the tester and calls made by your application. These logs should include all technical details you need.

Any call you make to our API will return with a ProbaseRequestId in the header. You can also use this in the logs to look up the details for a specific request.

OAuth2

These API's are accessible through OAuth2 using either the authorization code or the client credentials grant type. While it is not our intention to explain OAuth2 itself into detail, the following guides should help you get started. For more information on OAuth2 we recommend https://connect2id.com/learn/oauth-2.

There are two ways to connect with the Procurios API:

• Authorization code
• Client credentials

Authorization code

The authorization code grant type allows you as a client to use the Procurios API from the perspective of a user.

Procurios should have received:

• A list of allowed redirect urls:

You should have received:

• An OAuth2 client id: {clientId}
• An OAuth2 client secret: {clientSecret}
• A token request endpoint url: https://api.core.milieudefensie.nl/l/oauth2/token
• A client authorization endpoint url https://api.core.milieudefensie.nl/l/oauth2/authorize
• At least one scope to claim: {space separated list of scopes}

The flow of calls should be:

1. Direct the user to the authorization endpoint

   {clientAuthorizationEndPointUrl}?response_type=code&scope={space separated list of scopes}&client_id={clientId}&redirect_uri={redirectUrl}
   

   Example:

   https://procurios.com/l/oauth2/authorize?response_type=code&scope=profile&client_id=abc123&redirect_uri=example.com
   

2. Receive the user with his or her access code

   {redirectUrl}?code={code}
   

   Example:

   https://example.com?code=X
   

3. Call the token request endpoint with the access code and receive the access token

   POST {tokenRequestEndpointUrl}

   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&client_id={clientId}&code={code}&client_secret={clientSecret}
   

   Example:

   POST https://procurios.com/l/oauth2/token

   Content-Type: application/x-www-form-urlencoded
   Accept: application/json
   
   grant_type=authorization_code&client_id=abc123&code=X&client_secret=dfe456
   

   Access token response:

   {'access_token': '{accessToken}'}
   

4. Call the Procurios API with the header Authorization: Bearer accessToken
   (See below for examples)

Client credentials

The client credentials grant type allows you as a client to use the Procurios API from server to server without the context of a user. You should have:

• An OAuth2 client id: {clientId}
• An OAuth2 client secret: {clientSecret}
• A token request endpoint url: https://api.core.milieudefensie.nl/l/oauth2/token
• At least one scope to claim: {space separated list of scopes}

Request an access token

Before you can make a call to an OAuth2 endpoint, you must first call the token request endpoint with the client id and secret to receive the access token.

Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}&scope={space separated list of scopes}

The access token endpoint will reply with a response similar to this:

{
    "access_token": "{accessToken}",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "null"
}

This access token is valid for a limited number of seconds, 3600 in the example above. For every subsequent API endpoint call, call the Procurios API with the header:

Authorization: Bearer {accessToken}

Example API request

Once you have your access token, example requests could look something like:

Accept: application/vnd.procurios.application+json; version=1
Authorization: Bearer {accessToken}

Accept: application/vnd.procurios.application+json; version=1
Authorization: Bearer {accessToken}

{
"key": "value",
"otherKey": 2
        }