People

API endpoints for people-related data mapping operations.

Learn more about People Mapping.

List All People

get

This endpoint retrieves a list of all people in the data mapping system. It returns a comprehensive list of individuals, including their associated attributes and organizational details. For more details, refer to the Opsera API Documentation.

Use Cases

• Organizational Overview: Get a full list of people within the organization for reporting or analysis.

• Data Synchronization: Integrate personnel data with other systems requiring up-to-date information.

• Auditing and Compliance: Verify personnel records for compliance purposes.

---

Required Access

• Authentication: Bearer token is required.

• Permissions: User must have appropriate roles and rights to view people records.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Responses

200

Successfully retrieved the list of people.

application/json

countintegerOptional

Total number of people retrieved.

Example: 25

400

Bad request - Invalid input parameters.

application/json

401

Unauthorized - Authentication failed or insufficient permissions.

application/json

500

Internal server error.

application/json

get

/api/v2/data/people

HTTPcURLJavaScriptPython

GET /api/v2/data/people HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 25,
  "data": [
    {
      "id": "<mapping-id>",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "organization": "Opsera",
      "business": "Engineering",
      "department": "Platform",
      "group": "Phase 2",
      "team": "AOD",
      "createdAt": "2023-11-01T12:00:00.000Z",
      "updatedAt": "2023-11-05T12:00:00.000Z"
    }
  ]
}

Create a New Person

post

The People endpoint manages data about the users involved in your projects. Use these functions to create new people records, retrieve all people records, or access specific person details. For more details, refer to the Opsera API Documentation.

Use Cases

• Onboarding: Add new employees or collaborators to the system during the onboarding process.

• Organizational Mapping: Maintain an accurate mapping of personnel within your organization's structure.

• Data Integration: Synchronize personnel data with other systems that rely on up-to-date information.

---

Required Access

• Authentication: Bearer token is required.

• Permissions: User must have appropriate roles and rights to create people records.

---

Request Body Details

The request body must include the required attributes for the new person. The following fields are expected:

Required Fields:

• email: The email address of the person (must be unique).

• firstName: The person's first name.

• lastName: The person's last name.

Optional Fields:

• organization: The organization the person is associated with. Represents the highest entities while team represents the lowest.

• business: The business unit the person belongs to.

• department: The department the person is part of.

• group: The group the person is associated with.

• team: The team the person works with.

---

Important Notes!

• Unique Email: The email field must be unique across all people records.

• Required Fields: Ensure all mandatory fields are included in the request body.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Body

application/json

emailstring · emailRequired

The unique email address of the person.

Example: [email protected]

firstNamestringRequired

The first name of the person.

Example: John

lastNamestringRequired

The last name of the person.

Example: Doe

organizationstringOptional

The organization the person is associated with.

Example: Opsera.

businessstringOptional

The business unit the person belongs to.

Example: Engineering

departmentstringOptional

The department the person is part of.

Example: Platform

groupstringOptional

The group the person is associated with.

Example: Phase 2

teamstringOptional

The team the person works with.

Example: AOD

Responses

201

Person created successfully.

application/json

400

Bad request - Invalid or missing input data.

application/json

401

Unauthorized - Authentication failed or insufficient permissions.

application/json

409

Conflict - Duplicate email address.

application/json

500

Internal server error.

application/json

post

/api/v2/data/people

HTTPcURLJavaScriptPython

POST /api/v2/data/people HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 165

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "organization": "Opsera.",
  "business": "Engineering",
  "department": "Platform",
  "group": "Phase 2",
  "team": "AOD"
}

{
  "id": "25ce97e1-549b-4f31-bd01-80490847f8a6",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "organization": "Opsera",
  "business": "Engineering",
  "department": "Platform",
  "group": "Development Group",
  "team": "AOD",
  "createdAt": "2023-11-01T12:00:00.000Z"
}

Get a Specific Person

get

This endpoint retrieves detailed information about a specific person from the data mapping system using their email address. It allows you to fetch individual details to manage organizational hierarchies, project collaborations, and system integrations. For more details, refer to the Opsera API Documentation.

Use Cases

• Organizational Mapping: Fetch individual details to manage and map organizational hierarchies.

• Project Collaboration: Identify and retrieve collaborator details for projects or teams.

• System Integration: Retrieve person-specific information for data synchronization and integrations.

---

Required Access

• Authentication: Bearer token is required.

• API Scope: api

• Site Roles:

  • Opsera Administrator

  • Administrator

  • Power User

---

Important Notes!

• Email Format: The email parameter must be a valid email address.

• Case Sensitivity: Email addresses are case-insensitive.

• Data Sensitivity: Personal information is sensitive; handle it according to privacy policies and regulations.

• Error Handling: Appropriate HTTP status codes are returned for different error scenarios.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

emailstring · emailRequired

The email address of the person to retrieve.

Example: [email protected]

Responses

200

Successfully retrieved the person.

application/json

idstringOptional

Unique identifier for the person.

Example: <person-id>

emailstring · emailOptional

Email address of the person.

Example: [email protected]

firstNamestringOptional

First name of the person.

Example: John

lastNamestringOptional

Last name of the person.

Example: Doe

organizationstringOptional

Organization the person is associated with.

Example: Opsera

businessstringOptional

Business unit the person belongs to.

Example: Engineering

departmentstringOptional

Department of the person.

Example: Platform

groupstringOptional

Group the person is part of.

Example: Phase 2

teamstringOptional

Team the person belongs to.

Example: AOD

createdAtstring · date-timeOptional

Timestamp when the person was added to the system.

Example: 2023-11-01T12:00:00.000Z

updatedAtstring · date-timeOptional

Timestamp of the last update to the person's record.

Example: 2023-11-05T12:00:00.000Z

400

Bad Request - Invalid email format.

application/json

401

Unauthorized - Authentication failed or insufficient permissions.

application/json

404

Not Found - Person not found.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

get

/api/v2/data/people/{email}

HTTPcURLJavaScriptPython

GET /api/v2/data/people/{email} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "<person-id>",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "organization": "Opsera",
  "business": "Engineering",
  "department": "Platform",
  "group": "Phase 2",
  "team": "AOD",
  "createdAt": "2023-11-01T12:00:00.000Z",
  "updatedAt": "2023-11-05T12:00:00.000Z"
}

Update an Existing Person

put

This endpoint updates an existing person in the data mapping system using their email address as a unique identifier. It allows you to modify personal details and associated organizational attributes.

Use Cases

• Profile Updates: Keep individual records up-to-date with changes in personal or organizational information.

• Role Changes: Update a person's department, team, or role within the organization.

• Data Correction: Fix any inaccuracies in a person's record.

• Integration Synchronization: Reflect updates across integrated systems that rely on accurate personnel data.

---

Required Access

• Authentication: Bearer token is required.

• API Scope: api

• Site Roles:

  • Opsera Administrator

  • Administrator

  • Power User

---

Important Notes!

• Email Identifier: The email path parameter must correspond to an existing person in the system.

• Partial Updates: You can include only the fields you wish to update; unspecified fields will remain unchanged.

• Validation: Ensure that all provided data adheres to the expected formats and constraints.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

emailstring · emailRequired

The unique email address of the person to update.

Example: [email protected]

Body

application/json

firstNamestringOptional

The updated first name of the person.

Example: John

lastNamestringOptional

The updated last name of the person.

Example: Doe

organizationstringOptional

The updated organization the person is associated with.

Example: Opsera

businessstringOptional

The updated business unit the person belongs to.

Example: Engineering

departmentstringOptional

The updated department the person is part of.

Example: Platform

groupstringOptional

The updated group the person is associated with.

Example: Phase 2

teamstringOptional

The updated team the person works with.

Example: AOD

Responses

200

Person updated successfully.

application/json

idstringOptional

Unique identifier for the person.

Example: 25ce97e1-549b-4f31-bd01-80490847f8a6

emailstring · emailOptional

Email address of the person.

Example: [email protected]

firstNamestringOptional

First name of the person.

Example: John

lastNamestringOptional

Last name of the person.

Example: Doe

organizationstringOptional

Organization the person is associated with.

Example: Opsera

businessstringOptional

Business unit the person belongs to.

Example: Engineering

departmentstringOptional

Department the person is part of.

Example: Platform

groupstringOptional

Group the person is associated with.

Example: Phase 2

teamstringOptional

Team the person works with.

Example: AOD

updatedAtstring · date-timeOptional

Timestamp when the person was last updated.

Example: 2023-11-05T12:00:00.000Z

400

Bad Request - Invalid or missing input data.

application/json

401

Unauthorized - Authentication failed or insufficient permissions.

application/json

404

Not Found - Person not found.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

put

/api/v2/data/people/{email}

HTTPcURLJavaScriptPython

PUT /api/v2/data/people/{email} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 141

{
  "firstName": "John",
  "lastName": "Doe",
  "organization": "Opsera",
  "business": "Engineering",
  "department": "Platform",
  "group": "Phase 2",
  "team": "AOD"
}

{
  "id": "25ce97e1-549b-4f31-bd01-80490847f8a6",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "organization": "Opsera",
  "business": "Engineering",
  "department": "Platform",
  "group": "Phase 2",
  "team": "AOD",
  "updatedAt": "2023-11-05T12:00:00.000Z"
}