Project Creation using Third Party Access

Purpose/Overview

This API feature allows developers to programmatically create new projects within the system. It's useful for automating project setup, integrating with other applications, or bulk-importing projects from an external source. It solves the problem of manual project entry, reducing human error and saving time. This feature is intended for developers and system administrators who need to integrate with or automate the project management system. The value it brings is efficient, scalable, and automated project creation. 

Navigation Path:

To access this feature, use the provided API endpoints on Swagger UI. 

Things to Know:

• A valid OpenIDToauth token is required for access.

• The system supports two distinct methods: one for comprehensive project creation and one for basic projects.

• For a new project, the projectID in the request body must be set to 0. A project will also be created if the externalProjectID is 0. If either the projectID or the externalProjectID is not 0, the request will be treated as an update request for an existing project.

Key Benefits/Use Cases:

• Bulk Project Import: A system administrator can use the API to import hundreds of projects from a legacy system, automating a process that would be time-consuming and prone to errors if done manually. The benefit is a fast, accurate, and automated data migration.

• Integration with an External Tool: A development team can integrate the API with their project management software to automatically create a new project in the system whenever a new task is initiated. This ensures data consistency across platforms and saves time on duplicate data entry.

• Automated Workflow for New Client Onboarding: When a new client is signed in a CRM system, an automated script can use the API to create a new project for them. This streamlines the onboarding process, ensuring all new client projects are set up correctly from the start.

How It Works:

You have two options for creating a project via the API:

Option 1: Create a Project with All Related Data

Use this endpoint for a comprehensive project creation, including associated entities like milestones and contacts.

• Endpoint: POST /api/v1/projects

• Request Body: A JSON array of ProjectDetailRequest objects. Each object represents a project and its associated data.

Example Request Body:

[  {"projectID": 0,
    "projectName": "New Building Construction",
    "projectNumber": "PROJ-2025-001",
    "projectType": "Construction",
    "projectStatus": "Planning",
    "projectAddress": [   
   {    "addressLine1": "123 Main Street"      }    ],
    "projectMilestones": [   
   {    "milestoneName": "Phase 1 Complete",
        "dueDate": "2025-12-31"      }    ]  } ]

Option 2: Create a Basic Project

Use this endpoint for a simple project with core details only.

• Endpoint: POST /api/v1/projects/project

• Request Body: A JSON object of ProjectRequest.

Example Request Body:

{ "projectID": 0,
  "projectNum": "P-002",
  "projectName": "Website Redesign",
  "projectType": "IT",
  "projectStatus": "In Progress"
}

Related Features/Next Steps:

• Project Creation (Web)
• Project Creation (GIS)
• Project Creation Overview

FAQ/Troubleshooting:

Q: I'm getting a 401 Unauthorized error. What's wrong? 

A: This error indicates that your OpenIDToauth token is either missing, invalid, or expired. Ensure you are including a valid token in your request headers.

Q: Why would I get a 206 Partial Content response? 

A: This response occurs when you've sent a request to the comprehensive endpoint (/api/v1/projects) with multiple projects, and some projects were created successfully while others failed. Review the response body for details on which specific parts of the request failed.

Q: Can I use the basic project endpoint to add addresses later? 

A: Yes, the basic endpoint is for initial creation. You would need to use a separate API endpoint (e.g., an update or add-address endpoint) to add more details later.

Q: What do the different API response codes mean? 

A:

• 200 OK: The project was created successfully. The response object will contain a success field set to true.

• 400 Bad Request: The request body was invalid. Check for missing or incorrectly formatted fields.

• 500 Internal Server Error: An unexpected server error occurred. This indicates an issue on the server's end, and you should contact support.

Questions?  Contact us!