Articles on: API

Project API

The Project API in XperienceHR provides an interface for managing projects, including creating, updating, deactivating, and listing projects, ensuring seamless integration with external systems for project management and tracking.

This API supports XML & JSON format for structured data exchange and requires authentication via an API key.

By integrating the Project API, organizations can efficiently manage project lifecycle data, ensuring accurate project tracking and resource allocation.

Overview

API Type: REST
Supported Formats: XML
API Key: Generated in the app configuration
Method: POST, GET

Project Management

Functionality:
Create New Project
Update Project
Deactivate Project
Get All Projects

Create New Project

Parameter	Min	Max	Required	Information
Name	1	100	✅
Code	1	30	✅
Client Code	-	-	✅	Valid XPHR value
Client Name	-	-	❌	Valid XPHR value
Description	0	500	❌
Budget	0	Double_MAX_VALUE	❌
Duration	0	Integer_MAX_VALUE	❌
Billing Type	-	-	❌	Valid values: employee, activity, project
Rate	-	-	❌	Only relevant for Project Rate type
Billable	TRUE	FALSE	❌
Active	TRUE	FALSE	❌
Late Missing Notification	TRUE	FALSE	❌
SMS Notification	TRUE	FALSE	❌	Valid XPHR value
Email String	-	-	❌	Valid email address
Project Manager Logins	-	-	❌	Valid XPHR value
Cost Center Code	-	-	❌	Valid XPHR value
Cost Center Name	-	-	❌	Valid XPHR value

Multiple email addresses are separated with commas.

Cost Center Name & Code are required only when creating a new project. Updating Cost Center is not supported with this API.

Endpoint

https://[INSTANCE].xperience.app/externalRestApi/project/save?apiKey=[API_KEY]

https://test.xperience.app/externalRestApi/project/save?apiKey=jnas92kke529o1-en

<Projects>
  <Project>
    <active>true</active>
    <billable>true</billable>
    <billingType>employee</billingType>
    <name>API Project2</name>
    <code>APIPR2</code>
    <lateMissingNotification>true</lateMissingNotification>
    <lateMissingEmployeeSMSNotification>true</lateMissingEmployeeSMSNotification>
    <lateMissingEmailsString>test@flapps.com</lateMissingEmailsString>
    <projectManagerLogins>bdavid</projectManagerLogins>
    <duration>200</duration>
    <rate>40</rate>
    <budget>20000</budget>
    <Client>
      <code>Client BA</code>
      <name>Jim</name>
    </Client>
    <CostCenter>
      <code>TC</code>
      <name>Test Center</name>
    </CostCenter>
  </Project>
</Projects>

{
  "projects": [
    {
      "active": true,
      "billable": true,
      "billingType": "employee",
      "name": "API Project2",
      "code": "APIPR2",
      "lateMissingNotification": true,
      "lateMissingEmployeeSMSNotification": true,
      "lateMissingEmailsString": "test@flapps.com",
      "projectManagerLogins": "bdavid",
      "duration": 200,
      "rate": 40,
      "budget": 20000,
      "client": {
        "code": "Client BA",
        "name": "Jim"
      },
      "costCenter": {
        "code": "TC",
        "name": "Test Center"
      }
    }
  ]
}

<ProjectImportResponse>
  <Result>
    <status>OK</status>
    <code>APIPR2</code>
  </Result>
</ProjectImportResponse>

Update Project

To update project's information, match its code in request body and provide value(s) for data to be updated. Only Project code is a required value for update.

Endpoint

https://[INSTANCE].xperience.app/externalRestApi/project/save?apiKey=[API_KEY]

https://test.xperience.app/externalRestApi/project/save?apiKey=jnas92kke529o1-en

<Projects>
  <Project>
    <code>APIPR2</code>
    <budget>50000</budget>
  </Project>
</Projects>

{
  "projects": [
    {
      "code": "APIPR2",
      "budget": 50000
    }
  ]
}

<ProjectImportResponse>
  <Result>
    <status>OK</status>
    <code>APIPR2</code>
  </Result>
</ProjectImportResponse>

Get All Projects

Endpoint

https://[INSTANCE].xperience.app/externalRestApi/project/list?apiKey=[API_KEY]

https://test.xperience.app/externalRestApi/project/list?apiKey=jnas92kke529o1-en

<Projects>
  <Project>
    <active>true</active>
    <ProjectStatus>
      <code>ACTIVE</code>
    </ProjectStatus>
    <projectType>HOURLY</projectType>
    <billable>false</billable>
    <billableType>DEFAULT_NO</billableType>
    <name>Project 2</name>
    <code></code>
    <description></description>
    <lateMissingNotification>false</lateMissingNotification>
    <lateMissingEmployeeSMSNotification>false</lateMissingEmployeeSMSNotification>
    <ProjectManagers/>
    <ProjectTeamMembers>
      <ProjectTeamMember>
        <OU>
          <name>Main Legal Entity</name>
        </OU>
      </ProjectTeamMember>
    </ProjectTeamMembers>
    <rate>0.0</rate>
    <Client>
      <code>UNIQ</code>
      <name>James</name>
    </Client>
  </Project>
  <Project>
    <active>true</active>
    <ProjectStatus>
      <code>ACTIVE</code>
    </ProjectStatus>
    <projectType>HOURLY</projectType>
    <billable>false</billable>
    <billableType>DEFAULT_NO</billableType>
    <name>Project 3</name>
    <code></code>
    <description></description>
    <lateMissingNotification>false</lateMissingNotification>
    <lateMissingEmployeeSMSNotification>false</lateMissingEmployeeSMSNotification>
    <ProjectManagers/>
    <ProjectTeamMembers>
      <ProjectTeamMember>
        <OU>
          <name>Main Legal Entity</name>
        </OU>
      </ProjectTeamMember>
    </ProjectTeamMembers>
    <rate>0.0</rate>
    <Client>
      <code>UNIQ</code>
      <name>James</name>
    </Client>
  </Project>
</Projects>

Error Handling

Common errors help in debugging and correcting API usage issues.

Example 1: Missing Code

<ProjectImportResponse>
  <Result>
    <status>error</status>
    <Errors>
      <error>Code required</error>
    </Errors>
  </Result>
</ProjectImportResponse>

Example 2: Name Length Exceeded Error

<ProjectImportResponse>
  <Result>
    <code>APIPR2</code>
    <status>error</status>
    <Errors>
      <error>Name: String out of range. Maximal length: 100.</error>
    </Errors>
  </Result>
</ProjectImportResponse>

HTTP Response Codes

2XX Success - Operation completed successfully.
4XX Client Error - Likely an issue with the request, such as incorrect parameters or insufficient permissions. Returns an error message in text or XML format.
5XX Server Error - Indicates a server issue. Report this error if encountered.

Updated on: 16/03/2025

Was this article helpful?

Thank you!