This document describes the various categories of the API endpoints and provides a workflow sequence for how these endpoints are typically used within the EPR Partner API. Each category is broken down into specific processes or actions.

Authentication

Authentication endpoints secure a token necessary for authorizing subsequent API calls. Refer to Authentication and Partner Configuration for proper steps for authentication to EPR.

Project Creation

Step 1: Retrieve Configuration Data

Before creating a project, it's important to fetch the configuration data to ensure it can be correctly set up with valid data fields such as projectType, Statuses, etc. This involves making API calls to retrieve listTypes and their corresponding items.

Fetching List Types

Call this endpoint to retrieve all available list types, including options for project settings such as types and statuses. This information is crucial for populating your application's dropdowns or similar selection interfaces.

Endpoint: GET /configurations/listTypes

• Description: Retrieves a list of configurable types like project types, statuses, and other categories that are used across various endpoints to ensure data consistency.

Fetching List Items for Specific Types

Once you have the list types, fetch the items for specific types such as projectType and Statuses.

Endpoint: GET /configurations/listItems

• Parameters:

  • typeId: The ID of the type for which items are required (e.g., projectType, Statuses).

Step 2: Create a Project

With the necessary configuration data retrieved, create a project using the appropriate API endpoint.

Creating a New Project

Endpoint: POST /projects

• Required Fields:

  • projectNumber: Must be a unique identifier. Recommended using a user-known identifier for a better user experience

  • projectType_LIID: As retrieved from the configurations.

  • status_LIID: As retrieved from the configurations.

  • purpose_id: As retrieved from the configurations.

  • cycle_LIID: As retrieved from the configurations.

Step 3: Manage Contacts

This section explains how to add or update contact information associated with a project within the EPR system. It is recommended that new contacts be created each time rather than attempting to look up and match existing records.

Important Note:

Any field ending in _LIID needs a listItem ID to be populated. Ensure to retrieve these values through the configuration calls described earlier and store them for accurate contact creation.

Step 1: Retrieve Configuration Data

Before creating a contact, it's important to fetch the configuration data to ensure that the contact can be correctly set up with valid data fields such as contactType.

Fetch List Types

• Endpoint: GET /configurations/listTypes

• Description: Retrieves a list of configurable types like contact types, statuses, and other categories.

Fetch List Items for Specific Types

• Endpoint: GET /configurations/listItems

• Parameters:

  • typeId: The ID of the type for which items are required (e.g., contactType).

Step 2: Create a Contact

Endpoint Details:

Endpoint: POST /partner/project/:id/contacts

• Description: Creates a new contact record for the specified project. You will need the Id

Required Fields:

• firstName: The first name of the contact.

• lastName: The last name of the contact.

• email: The email address of the contact.

• contactType_LIID: ListItem ID for the type of contact (e.g., owner, contractor).

Optional Fields:

• phone: Phone number of the contact.

• address: Address of the contact (if different from the project's address).

• role: The role of the contact within the project.

• organization: The organization the contact belongs to.

Example Process

1. Retrieve List Types:

   • Fetch the available list types that include contactType.

2. Retrieve List Items:

   • Get the items for the contactType to ensure valid entries.

3. Create a Contact:

   • Use the POST /partner/project/:id/contacts endpoint with the required and optional fields populated correctly.

Summary of Workflow

1. Retrieve Configuration Data:

   • Fetch list types and corresponding list items to populate fields like contactType.

2. Create a Contact:

   • Use the retrieved configuration data to create a new contact for a project using the POST /partner/project/:id/contacts endpoint.

Step 4: Manage Addresses

This section explains how to add or update address information associated with a project or a contact within the EPR system. It is recommended that new addresses be created each time rather than attempting to look up and match existing records.

Step 1: Retrieve Configuration Data

Before creating an address, it's important to fetch the configuration data to ensure that the address can be correctly set up with valid data fields such as streetType, state, and country.

Fetch List Types

• Endpoint: GET /configurations/listTypes

• Description: Retrieves a list of configurable types like streetType, state, country.

Fetch List Items for Specific Types

• Endpoint: GET /configurations/listItems

• Parameters:

  • typeId: The ID of the type for which items are required (e.g., streetType, state, country).

Step 2: Create a Project Address

Endpoint Details:

Endpoint: POST /partner/project/:id/addresses

• Description: Creates a new address record for the specified project.

Recommended Required Fields:

• streetNumber: The number of the street address.

• streetName: The name of the street.

• city: The city of the address.

• zipCode: The postal code.

• streetType_LIID: ListItem ID for the type of street (e.g., Avenue, Street).

• state_LIID: ListItem ID for the state.

• country_LIID: ListItem ID for the country.

Optional Fields:

• vendor_id: An optional identifier for the vendor.

• siteName: Optional name of the site.

• streetName2: Additional street name information.

• unit: Unit number or designation.

• county: The county of the address.

• parcel: Parcel identifier.

• lotNumber: Lot number.

• tractNumber: Tract number.

• longitude: Longitude coordinate.

• latitude: Latitude coordinate.

• direction_LIID: ListItem ID for street direction (e.g., N, S, E, W).

Step 3: Create a Contact Address

Endpoint Details:

Endpoint: POST /partner/person/:user_id/addresses

• Description: Creates a new address record for the specified contact.

Recommended Required Fields:

• Similar to project addresses, recommended required fields include streetNumber, streetName, city, zipCode, streetType_LIID, state_LIID, and country_LIID.

Optional Fields:

• Same optional fields as for project addresses including vendor_id, siteName, streetName2, unit, county, parcel, lotNumber, tractNumber, longitude, latitude, direction_LIID.

Workflow Summary

1. Retrieve Configuration Data:

   • Fetch list types and corresponding list items to populate fields like streetType, state, and country.

2. Create a Project Address:

   • Use the retrieved configuration data to create a new address for a project using the POST /partner/project/:id/addresses endpoint.

3. Create a Contact Address:

   • Similarly, create a new address for a contact using the POST /partner/person/:user_id/addresses endpoint, ensuring all necessary fields are populated.

Step 5: Documents

This section explains how to upload documents and attachments within the EPR system. Documents and attachments serve different purposes, and this guide will outline the processes and endpoints for each, ensuring partners can effectively upload both types.

Key Differences:

• Documents: These are typically main files such as plans, drawings, or specifications that are critical to project approval processes. Any pdf file that requires plan review should be uploaded as a Document.
  

• Attachments: Supplementary files such as additional notes, references, or secondary documents that support the main documents.
  

Step 1: Retrieve Configuration Data

Retrieving any necessary configuration data before uploading documents or attachments is important to ensure proper categorization and handling of these files.

Document Upload Process

Step 1: Obtain Document Upload URL

Endpoint: GET /partner/documentUploadUrl

• Description: Retrieves a pre-signed URL to upload the document to the file storage.

Request Parameters:

• filename (required): The name of the file to be uploaded.

Example Request:

GET /partner/documentUploadUrl?filename=my_document.pdf

Response:

Response:
{
    "success": true,
    "message": "Use the method and URL to put object to S3",
    "data": {
        "method": "PUT",
        "url": "<S3 pre-signed URL>",
        "contentType": "application/pdf",
        "filename": "my_document.pdf",
        "filePath": "tmp/documents/1706565016288/my_document.pdf"
    }
}

Step 2: Upload Document to S3

Use the provided method and URL to upload the file to the S3 storage.

Step 3: Complete File Upload

Endpoint: POST /partner/uploadDocument

• Description: Completes the document upload process by confirming the upload and associating it with a project.

Request Body:

{
    "project_id": "123",
    "filename": "my_document.pdf",
    "vendor_id": "456",
    "filePath": "tmp/documents/1706565016288/my_document.pdf"
}

Attachment Upload Process

Step 1: Obtain Attachment Upload URL

Endpoint: GET /partner/attachmentUploadUrl

• Description: Retrieves a pre-signed URL for uploading the attachment to the file storage.

Request Parameters:

• filename (required): The name of the attachment to be uploaded.

Example Request:

GET /partner/attachmentUploadUrl?filename=my_attachment.docx

Response:

{
    "success": true,
    "message": "Use the method and URL to put object to S3",
    "data": {
        "method": "PUT",
        "url": "<S3 pre-signed URL>",
        "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "filename": "my_attachment.docx",
        "filePath": "tmp/attachments/1706565016288/my_attachment.docx"
    }
}

Step 2: Upload Attachment to S3

Use the provided method and URL to upload the attachment to the S3 storage.

Step 3: Complete Attachment Upload

Endpoint: POST /partner/projectAttachments

• Description: Completes the attachment upload process by confirming the upload and associating it with a project.

Request Body:

{
    "project_id": "123",
    "filename": "my_attachment.docx",
    "vendor_id": "456",
    "filePath": "tmp/attachments/1706565016288/my_attachment.docx"
}

Summary of Workflow

1. Retrieve Configuration Data:

   • Fetch list types and corresponding list items to populate fields like contactType.

2. Document Upload:

   • Obtain a pre-signed URL for the document.

   • Upload the document to S3 using the pre-signed URL.

   • Confirm the upload using the POST /partner/uploadDocument endpoint.

3. Attachment Upload:

   • Obtain a pre-signed URL for the attachment.

   • Upload the attachment to S3 using the pre-signed URL.

   • Confirm the upload using the POST /partner/projectAttachments endpoint.

Document Intake, Document Versioning and Assignment Management

MVP Scope:

Document intake, document versioning, and assignment management are critical processes that the end user will handle manually during the MVP phase. This approach ensures the essential functionality is validated and approved before automating these processes.

Helpful links for the manual process in EPR:

Document Management

Performing Intake

Deliverables

This section explains how to handle deliverables within the EPR system during the MVP phase. Deliverables typically include documents, attachments, and comment reports. Users can retrieve these items individually or as a ZIP package.

MVP Process

Step 1: End User Selection

The end user will select all the documents, attachments, and comment reports they wish to send back to the integrated solution via the deliverables page.

Read more details on the user experience: Preparing Document Deliverables - ePlansoft Review (EPR) Wiki - Confluence (atlassian.net)

Step 2: Receiving JSON Array

A JSON array containing the details of the selected deliverables is sent back to an endpoint. This allows the integrated solution to make the necessary calls to retrieve the files individually or as a ZIP package.

Example JSON Array:

{
	"documentVersionIds": [
		532,
		535
	],
	"attachmentIds": [
		189
	],
	"project_id": 233,
	"projectNumber": "2024102849,
	"project_vendor_id": "3895726"
}

Option 1: Retrieve Files Individually

Step 1: Retrieve Individual Document Links

Endpoint: post /deliverable/getSingleFileDeliverables

• Description: Completes the deliverable creation process by confirming the upload and associating it with a project. This endpoint finalizes the process by linking the documents and attachments with the specified project.

Request Parameters:

The request should be made with a JSON body containing the following parameters:

• project_id (required): The ID of the project to which the deliverable is related.

• documentVersion_ids (required): An array of IDs of document versions included in the deliverable.

• closedComments (required): Recommended to be set to False.

• commentResponses (required): Recommended to be set to False.

• comments (required): Recommended to be set to True.

• sketches (required): Recommended to be set to True.

• stamps(required): An array of IDs of groups that should have access to the deliverable.

• timeZoneOffset (optional): System will set the timezone offset to match EPR. Only use field if you need a different timezone then the Agency is set to.

• sign (optional): Applies digital signature to printed PDFs. Recommened to be set to False

Example Request Format:

{
"project_id": 502,
"documentVersion_ids": [2405, 2408, 2409 ],
"closedComments": false,
"commentResponses": false,
"comments": true,
"sketches": true,
"stamps": true,
"timeZoneOffset": 4,
"sign": false
}

Response:

Copy code

Step 2: Download the Documents

Use the provided method and URL to download the Documents from S3 storage.

Step 3: Download the Attachments

Endpoint Details:

Endpoint: GET /partner/projectAttachments/:attachmentId/file

• Description: Download the file associated with the given attachment ID.

URL Parameters:

• attachmentId (required): The unique identifier of the attachment you wish to download.

Example Request:

GET /partner/projectAttachments/12345/file

Option 2: Create a Deliverable ZIP Package

Step 1: Obtain ZIP Package Creation URL

Endpoint: post /partner/deliverables

• Description: Completes the deliverable creation process by confirming the upload and associating it with a project. This endpoint finalizes the process by linking the documents and attachments with the specified project.

Request Parameters:

The request should be made with a JSON body containing the following parameters:

• project_id (required): The ID of the project to which the deliverable is related.

• filename (required): The desired name of the ZIP package.

• documentVersion_ids (required): An array of IDs of document versions included in the deliverable.

• attachment_ids (required): An array of IDs of attachments included in the deliverable.

• isActive (required): Boolean indicating if the deliverable is active.

• vendor_id (optional): The ID of the vendor responsible for the file, if applicable.

• group_ids (optional): An array of IDs of groups that should have access to the deliverable.

• user_ids (optional): An array of IDs of users that should have access to the deliverable.

• makePublic (optional): Boolean indicating if the deliverable should be made public. Please set to True.

Example Request Format:

{
  "project_id": 0,
  "filename": "string",
  "documentVersion_ids": [
    22,58,67
  ],
  "attachment_ids": [
    15,68,55
  ],
  "isActive": true,
  "vendor_id": "string",
  "group_ids": [
    0
  ],
  "user_ids": [
    0
  ],
  "makePublic": true
}

Response:

{
  success: true,
  message: 1 record(s) found,
  data: 
{
    link: linkvaluehere,
    isActive: true,
    hash: e4e24204d45e24dc0ffa3dcda15d66d8c7a689237ed6088ed8834afab4e2d44bdd8982ade0f664e3f6f7d5723f08f0a1e70f79739fb67b8f0f56ad07134c50bc,
    id: 190,
    project_id: 233,
    filename: Test.zip,
    updatedAt: 2024-06-17T16:47:21.474Z,
    createdAt: 2024-06-17T16:47:16.818Z
  }
}Copy code

Step 2: Download the ZIP

Use the provided method and URL to download the ZIP package to the S3 storage. base URL + link value from the previous call’s response body.

Conclusion

This document provides a comprehensive overview of the essential API endpoints for the Minimum Viable Product (MVP) integration with the EPR system. By following the outlined steps and utilizing the provided endpoints, partners can effectively manage project creation, contact and address management, document uploads, and deliverables within the EPR platform.

Next Steps: Beyond the MVP

As you become more familiar with the EPR API and its capabilities, you may find the need to extend beyond the MVP functionalities. For advanced features such as automated document intake, versioning, and assignment management, please refer to our "Beyond the MVP" documentation. This extended guide will provide deeper insights and additional tools to streamline your integration further and enhance the overall efficiency of your workflows.

For detailed guidance on advanced features, visit the "Beyond the MVP" documentation.

Need Help?

For support and inquiries, reach out to:
Channel Partner - Scott Garner sgartner@eplansoft.com
Integration Manager - Eric Niday eniday@eplansoft.com
General Support - support@eplansoft.com