Introduction

This Fresh Projects API provides endpoints for retrieving projects, leads, companies, and employees from Fresh Projects.

Authentication

Basic Authentication using username and password. All requests also need to pass an API KEY in the headers.

The username and password used to authenticate requests must be a valid user on your Fresh Projects account and must have a Administrator license. Please note that any request made to the API will create a new session for this user - thereby expiring any other session the user may already have. So it is recommended that a dedicated user account be used for all API requests.

Please contact support (support@gofreshprojects.com) to get your API KEY.

Error Codes

Polling for Changes

All endpoints will only return any new items since the last time the user (whose credentials are in the request) performed a check on that endpoint.

This means that if you have previously successfully retrieved a list of new items, and assuming that now new items have subsequently been added in Fresh Projects, the next request to that endpoint will return an empty array.

Sample Data

Because all endpoints (as explained above) will only return any new items since the last request, it is useful during testing to force a non-empty response. To do this, set the isloadingsample header in your request to true.

Deduplication

Including the ispopulatingdedupe header in your request will result in the API responding with the unique ids of all items from the endpoint, subject to the Data Limits described below. 

Sample Deduplication Response:

[
  { "id": "projectId1" },
  { "id": "projectId2" }
]

Data Limits

The maximum number of items return from any endpoint is 1000.

Endpoints

BASE API URL

https://api-uk.gofreshprojects.com/apiV1

AUTHENTICATE

GET /me

Description: Use this endpoint to check your authentication credentials and API KEY are working correctly

Request Headers:

• Authorization: Basic auth credentials (Base64 encoded username:password)
• api: your API KEY

Request Body:

• None

Response:

• Status: 200 OK
• Content-Type: application/json
• Body: JSON

    {
      "id": "userId",
      "email": "bob@builder.com",
    }

NEW PROJECT

GET /newproject

Description: Retrieves a list of new projects created since the last request

Request Headers:

• Authorization: Basic auth credentials (Base64 encoded username:password)
• api: your API KEY
• isloadingsample (optional): Boolean indicating whether to load a sample dataset.
• ispopulatingdedupe (optional): Boolean indicating whether to populate dedupe IDs.
• status (optional): Filter projects by status (opportunity, active).

Request Body:

• None

Response:

• Status: 200 OK
• Content-Type: application/json
• Body: JSON

  [
    {
      "id": "projectId1",
      "name": "Project A",
      "code": "PA123",
      "description": "Project A description",
      "createdAt": "2024-08-17T12:34:56Z",
      // ... other project properties
    },
    {
      "id": "projectId2",
      "name": "Project B",
      // ...
    }
  ]

NEW LEAD

GET /newlead

Description: Retrieves a list of new leads created since the last request

Request Headers:

• Authorization: Basic auth credentials (Base64 encoded username:password)
• api: your API KEY
• isloadingsample (optional): Boolean indicating whether to load a sample dataset.
• ispopulatingdedupe (optional): Boolean indicating whether to populate dedupe IDs.

Request Body:

• None

Response:

• Status: 200 OK
• Content-Type: application/json
• Body: JSON

  [
    {
      "id": "leadId1",
      "name": "Project A",
      "code": "PA123",
      "createdAt": "2024-08-17T12:34:56Z",
      // ... other lead properties
    },
    {
      "id": "leadId2",
      "name": "Project B",
      // ...
    }
  ]

NEW COMPANY

GET /newclient

Description: Retrieves a list of new companies (clients) added since the last request

Request Headers:

• Authorization: Basic auth credentials (Base64 encoded username:password)
• api: your API KEY
• isloadingsample (optional): Boolean indicating whether to load a sample dataset.
• ispopulatingdedupe (optional): Boolean indicating whether to populate dedupe IDs.

Request Body:

• None

Response:

• Status: 200 OK
• Content-Type: application/json
• Body: JSON

  [
    {
      "id": "clientId1",
      "name": "Client A",
      // ... other client properties
    },
    {
      "id": "clientId2",
      "name": "Client B",
      // ...
    }
  ]

NEW EMPLOYEE

GET /newemployee

Description: Retrieves a list of new employees added since the last request

Request Headers:

• Authorization: Basic auth credentials (Base64 encoded username:password)
• api: your API KEY
• isloadingsample (optional): Boolean indicating whether to load a sample dataset.
• ispopulatingdedupe (optional): Boolean indicating whether to populate dedupe IDs.

Request Body:

• None

Response:

• Status: 200 OK
• Content-Type: application/json
• Body: JSON

  [
    {
      "id": "employeeId1",
      "name": "Employee A",
      // ... other project properties
    },
    {
      "id": "employeeId2",
      "name": "Employee B",
      // ...
    }
  ]

UPDATED PROJECT

GET /updatedproject

Description: Retrieves a list of projects that have changed their project status or pipeline stage since the last request

Request Headers:

• Authorization: Basic auth credentials (Base64 encoded username:password)
• api: your API KEY
• isloadingsample (optional): Boolean indicating whether to load a sample dataset.
• ispopulatingdedupe (optional): Boolean indicating whether to populate dedupe IDs.

Request Body:

• None

Response:

• Status: 200 OK
• Content-Type: application/json
• Body: JSON

  [
    {
      "id": "projectChangeId1",
      "name": "Project A",
      "code": "PA123",
      "projectStatus": "Active",
      "changedAt": "2024-08-17T12:34:56Z",
      // ... other project change properties
    },
    {
      "id": "projectChangeId2",
      "name": "Project B",
      // ...
    }
  ]