Skip to main content

Upload and Manage Developer Records Using the Harness SEI API

Overview​

This page explains how to create and update developer records programmatically, provides best practices for integrating with external systems, and includes troubleshooting information to validate developer data before applying changes.

For a complete list of endpoints and schema definitions, see the Harness API reference documentation.

Before you begin​

To call the SEI API, you’ll need:

  • A Harness API key

  • A Harness account identifier

  • A base URL. All API URIs are relative to the SEI service endpoint for your region.

    • Prod 1: https://app.harness.io/prod1/sei/api/
    • Prod 2: https://app.harness.io/gratis/sei/api/
    • EU: https://accounts.eu.harness.io/sei/api/

Authentication​

All Harness SEI APIs require authentication using a Harness API key.

To authenticate:

  1. Create a Harness API key.

  2. Include the API key in your request header:

    curl -X GET \
      "https://app.harness.io/gateway/sei/api/v2/developers/schema" \
      -H "x-api-key: <YOUR_API_KEY>" \

Manage developer records​

The Harness SEI API enables programmatic management of developer records. You can use the API to automate updates by writing scripts or jobs that trigger record changes whenever your source of truth (such as an HR system) changes.

This reduces manual edits, lowers the risk of errors, and ensures developer data stays accurate and consistent for productivity and DORA metrics.

Initial setup (Upload and save)​

The developer schema and baseline data must first be established using the upload and save workflow.

danger

Reupload, approve, and upsert operations will return 412 Precondition Failed if attempted before completing this initial setup.

  • Endpoint: POST /v2/developers
  • Authentication: Requires an API key with developer_records:write scope.
  • Content-Type: multipart/form-data

Upload a CSV file containing developer data. Returns a preview with field mappings and validation errors. Response includes versionId for tracking.

For example:

curl -X POST \
  'https://app.harness.io/prod1/sei/api/v2/developers' \
  -H "accept: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -F "file=@sample_file.csv;type=text/csv"

Bulk update (Re-upload & approve)​

  • Re-upload Endpoint: PUT /v2/developers
  • Approve Endpoint: PATCH /v2/developers/versions/{versionId}
  • Authentication: Requires an API key with developer_records:write scope.

Re-upload a new developer CSV file (auto-maps fields) and approve changes to activate. Returns review data.

For example:

# Re-upload
curl -X PUT \
  'https://app.harness.io/prod1/sei/api/v2/developers' \
  -H "accept: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -F "file=@Updated_Developers.csv;type=text/csv"

# Approve
curl -X PATCH \
  'https://app.harness.io/prod1/sei/api/v2/developers/versions/<VERSION_ID>' \
  -H "accept: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'

List and download developers​

  • List Endpoint: GET /v2/developers
  • Download Endpoint: GET /v2/developers (Accept: text/csv)
  • Authentication: Requires an API key with developer_records:read scope.

Retrieve filtered/sorted list of developers or download a full CSV file. Supports query parameters such as emails, developerRefIds, searchKey, sortOrder, pageIndex, and pageSize.

For example:

# List JSON
curl -X GET \
  'https://app.harness.io/prod1/sei/api/v2/developers?searchKey=department&searchValue=Engineering&pageIndex=0&pageSize=50' \
  -H "accept: application/json" \
  -H "x-api-key: <YOUR_API_KEY>"

# Download CSV
curl -X GET \
  'https://app.harness.io/prod1/sei/api/v2/developers' \
  -H "accept: text/csv" \
  -H "x-api-key: <YOUR_API_KEY>"

Developer endpoints​

Old EndpointNew EndpointMethod ChangeNotes
POST /v2/developers/uploadPOST /v2/developersNoneMultipart form data
POST /v2/developers/reuploadPUT /v2/developersPOST → PUTMultipart form data
POST /v2/developers/uploads/{uploadId}/savePUT /v2/developers/versions/{versionId}/fieldMappingsPOST → PUTPath parameter change
POST /v2/developers/uploads/{uploadId}/approvePATCH /v2/developers/versions/{versionId}POST → PATCHPath parameter change
POST /v2/developers/listGET /v2/developersPOST → GETQuery parameters
GET /v2/developers/downloadGET /v2/developersNoneContent negotiation

Troubleshooting​

Developer operations (save, upsert, delete, and reupload) perform comprehensive validation and return structured error responses when validation fails.

Validation errors help identify and resolve issues with CSV uploads, field mappings, and developer record data before any changes are applied.

Error types​

Error TypeWhen it OccursDetails
REQUIRED_FIELD_MISSINGA required field is missing from the CSV upload or field mappings.Required fields include name, email, and manager_email (if configured), as well as any fields used in org tree filters or group-by configurations. Triggered during file upload when mappings don’t include required fields.
REQUIRED_VALUE_MISSINGRequired fields have empty or blank values in developer records.Applies to name and email (always required). Triggered when any developer record has empty/null values for these fields.
DUPLICATE_EMAILMultiple developer records share the same email address.Each developer must have a unique email. Applies to all developer operations (save, upsert, delete).
CIRCULAR_REFERENCEManager-employee relationships form circular references.Example: A reports to B, and B reports to A. Detected through graph traversal of manager-employee relationships. Prevents infinite loops in the org hierarchy.
MANAGER_EMAIL_MISSING_IN_DEVELOPER_EMAILSA developer’s manager_email value doesn’t exist in the dataset.Manager email can be empty, but if provided, it must match an existing developer’s email. Ensures all managers are also developers.
MISSING_NAME_OR_EMAIL_OR_MANAGER_EMAIL_FIELD_MAPPINGEssential field mappings (NAME, EMAIL, or MANAGER_EMAIL) are missing from field configuration.Triggered during save when required field types are not mapped to CSV columns. Prevents saving when core identification fields are undefined.
INVALID_CSVThe uploaded CSV file format is invalid or corrupted.Triggered during upload when parsing fails. Causes include malformed structure, encoding issues, or file corruption.
EMPTY_CSVThe uploaded CSV file contains no data rows.Triggered when the file has only headers or is entirely empty. Prevents processing of empty datasets.
BLANK_CSV_COLUMN_NAMEThe CSV contains columns with blank or empty header names.Triggered during upload when headers are missing or contain only whitespace. Ensures all columns have valid names for mapping.

Error response structure​

All validation errors are returned in the following structure:

{
  "status": "FAILURE",
  "errors": [
    {
      "errorType": "ERROR_TYPE_NAME",
      "fieldName": "field_name_or_null",
      "errorDeveloperCount": 10,
      "sampleErrorDevelopers": [
        {
          "field1": "value1",
          "field2": "value2"
        }
      ]
    }
  ]
}
  • sampleErrorDevelopers is limited to a partial list of records per error type.
  • errorDeveloperCount shows the total number of records affected.

Multiple error types can be returned simultaneously and validation occurs before any data is saved to prevent partial updates.