Before You Begin

In addition, you will need to familiarize yourself with the OAuth 2.0 authentication protocol as access to the
Procore API is secured by the authorization and authentication requirements of OAuth 2.0. Applications you develop for integrating with Procore must
implement OAuth 2.0.

HTTPS Protocol Requirement

Because all Procore API resources are protected by Secure Sockets Layer (SSL) encryption, any call you make to
a Procore API resource must use the HTTPS scheme in the URL. SSL establishes an
encrypted link between the Procore resource server and your application. This link ensures that all data passed
between the resource server and your appplication remain private.

cURL and Postman

Two popular web development test tools - cURL and Postman - can be used to explore the capabilities of the Procore API without having to fully build
out your application. In the following sections we use these tools to illustrate how you can make your first call to the Procore API. If you are unfamiliar with
these tools, here are some helpful resources to get you started.

Let’s break this URL into its constituent components, so we can examine it in more detail:

The first piece of the URL - https://login.procore.com/oauth - is known as the Base URL. We include the Base URL with every call we make to
the Procore API.

Next, we see the endpoint definition itself - /authorize.

Following that, three distinct query parameters are defined - response_type, client_id, and
redirect_uri. A question mark symbol is used to separate
the query parameters from the rest of the URL.Let’s have a look at each of these parameters:

response_type - set to a value of ‘code’, indicates that we want the Procore API /authorize endpoint to return an authorization code for us.

client_id - should match what you retrieve from your application page on the Developer Portal.

redirect_uri - should be set to ‘urn:ietf:wg:oauth:2.0:oob’. This allows you to obtain an authorization code without having to run a web server locally

If we build up this URL in the address bar of our browser and send it, the Procore API responds with a panel displaying the returned authorization code.

It is important to note that the authorization code you obtain is only valid for ten minutes. As such, you must use this code to retrieve an access
token within the 10 minute expiration period. Otherwise, you will need to call the /authorize endpoint again to obtain a valid authorization code.

2. Retrieve an Access Token

Now that we have an authorization code, we can use that to retrieve an access token. We’ll use the Procore API /token endpoint for this step.
Our cURL command for retrieving an access token will pass the following parameters:

client_id - should match what you retrieve from your application page on the Developer Portal.

client_secret - should match what you retrieve from your application page on the Developer Portal.

code - is the authorization code string you captured in the previous step using the /authorize endpoint.

grant_type - is set to “authorization_code”.

redirect_uri - should be set to “urn:ietf:wg:oauth:2.0:oob” to be consistent with our example.

Examining this command we see that we use -F command flags to specify each of the required parameters as being form field data.
In addition, we use backslash characters to denote line breaks which makes the example more readable. Finally, we use the -X POST
flag to tell cURL that we are sending a POST call to the Procore API /token endpoint. Running this command
returns a JSON block similar to the following. Let’s take a look at it’s contents.

3. Making a Call to the Procore API

Now that we have successfully retrieved an access token, we can use it to make our first call to the Procore API. For this example,
we’ll use the simple /me endpoint to show that we can successfully contact the Procore API server and
return information about the currently logged in user. Again, we’ll use cURL to demonstrate this.

First, we’ll build up our cURL command using the following syntax, specifying the authorization code as a header parameter:

Using Postman to Make Your First Procore API Call

Postman is a very popular and capable platform for working with and testing REST APIs. While you are in the exploratory
stage with the Procore Connect API, we recommend Postman as a platform for familiarizing yourself with the various endpoints
exposed through the API. Postman is a feature-rich application that can run as a Chrome app or natively in Windows or Mac OSX.

If you have not done so already, visit the Postman website, download the appropriate
installation package, and install as instructed. The examples presented in the following sections are based on Postman v5.3.3. In addition, we recommend

1. Configure OAuth 2.0 in Postman

Before you can make a call to the Procore API using Postman, you must configure OAuth 2.0 authorization using Postman's token management tool. See
Generating OAuth 2.0 Tokens in Postman for the steps to accomplish this. Note that this example uses a development sandbox environment, but you can just
as easily configure OAuth 2.0 and generate access tokens for your production environment.

2. Making a Call to the Procore API

Once you have configured OAuth 2.0 in Postman and are able to successfully generate access tokens using the token management tool, you can use these
tokens to authenticate calls to the Procore API. The example below illustrates a simple call to the List Projects endpoint using Postman.

Let's break down this example call:

First, we set the HTTP action to GET.

We then enter the URL for the List Projects endpoint as https://api.procore.com/vapid/projects?company_id=1234. Note that we've
used a fictitous company_id of '1234', so you will want to substitute your own valid company_id value.

The Authorization Type is set to 'Inherit auth from parent' because we have configured OAuth 2.0 in Postman at the collection level as described in
Generating OAuth 2.0 Tokens.