Quick Start Guide

Learn how to build and test your first Procore App.

Introduction

This guide walks you through the process of creating and testing a basic app with Procore’s API, using User-Level Authentication. By following these steps, you’ll install your app in a Sandbox environment, configure components, and generate an access token—all within 15 minutes.

Steps to Begin Making Your First API Call

Prerequisites

  1. A Procore Developer Account.
  2. Basic knowledge of OAuth 2.0 and redirect URIs.
  3. An API testing tool, such as Postman or cURL.

Step 1: Create Your App in the Developer Portal

Before getting started, you will need to have created a Developer Account by signing up through the Procore Developer Portal and verify your information.

  1. Log in to the Procore Developer Portal.
  2. Navigate to My Apps and click Create New App.
  3. Provide a meaningful app name (e.g., "QuickStart Test App").
  4. Click Create App to proceed.

Step 2: Add a Data Connector Component

A Data Connector Component enables your app to retrieve data from Procore’s API.

  1. Click the down arrow to expand the Data Connector Components section.
  2. Select Add Components.
  3. On the right-hand side, select User Level Authentication.
  4. Click Save Component at the bottom-right of the side panel.
  5. Click Create Version in the near the top right then follow the prompts.

Step 3: Update Your App’s URIs

To handle authentication, update your app’s redirect URIs. It's important to note that this specific redirect URI is meant for testing purposes only.

  1. In your app, select OAuth Credentials on the left hand side.
  2. Under Sandbox OAuth Credentials, click into the Redirect URI field.
  3. In this field, paste the following text: urn:ietf:wg:oauth:2.0:oob
  4. Click Update in the bottom right corner.

Step 4: Install Your App in the Sandbox

Every created app comes with a Developer Sandbox intended to be your primary testing environment. To access the Developer Sandbox, check your email inbox for a message prompting you to create a password. Additionally, you can find the URL to your Sandbox by navigating to the Sandbox OAuth Credentials section of your app.

Please note that only the App Creator will be automatically added to the Developer Sandbox. If you want to add internal and external testers to this environment, learn how to do so by visiting Add a User Account to the Company Directory.

  1. Log into your Developer Sandbox and select the corresponding Company
  2. Select Company Tools at the top, then click on the Admin tool.
  3. On the right-hand side, click App Management.
  4. Click Install App and choose Install Custom App.
  5. Paste the previously copied App Version Key.
  6. Click Install.
  7. Click Install again to confirm the installation.

Step 5: Generate a Code for User Authentication

Now that your app is installed, we need to generate a code, which will be exchanged for an access token.

  1. In the following URL, replace the CLIENT_ID variable with that of your Sandbox Credentials, which can be found in your app through the Developer Portal:
    • https://login-sandbox.procore.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob
  2. Open the edited URL in your web browser.
    • This may prompt you to log in, if you are already not signed into Procore.
    • Additionally, you may have to select Approve if the app is accessing your information for the first time.
  3. Once successfully done, copy the code value as it’s required for the next step.

Step 6: Exchange the Code for an Access Token

To retrieve an access token, you’ll exchange the code for a token using Postman (or any API client):

  1. In Postman, create a POST request to: https://login-sandbox.procore.com/oauth/token/.
  2. Add the following to the Body as x-www-form-urlencoded:
    • grant_type: authorization_code
    • code: Your authorization code (from Step 5).
    • client_id: Your app’s Client ID.
    • client_secret: Your app’s Client Secret.
    • redirect_uri: urn:ietf:wg:oauth:2.0:oob.
  3. Click Send.

If successful, you’ll receive a response containing your access token similar to the example below: 
{
  "access_token": "dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781",
  "token_type": "bearer",
  "expires_in": 5400,
  "refresh_token": "76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c",
  "created_at": 1508271900
}

Step 7: Test API Requests

Now that we have an access token, we can begin using the Procore APIs to it's full capabilities by calling on data that is in Procore, such as List Available Companies and List Projects.

Additionally, you can use the access token to create new data in Procore, or update existing data by using the corresponding Procore REST APIs.

1. To generate a list of available companies based on your access token in Postman:

  1. In Postman, create a POST request to: https://sandbox.procore.com/rest/v1.0/companies.
  2. Add the following header: Authorization: Bearer ACCESS_TOKEN.
  3. Once successfully done, copy the ID of the company where your app is installed as it’s required for the next step.
2. To generate a list of projects from a specific company based on your access token in Postman:
  1. In Postman, create a POST request to: https://sandbox.procore.com/rest/v1.0/companies.
  2. Add the following headers:
    • Authorization: Bearer ACCESS_TOKEN.
    • Procore-Company-Id: The ID of the company (from Step 7.1).