Overview

DataServ provides secure, RESTful External APIs that enable organizations to automate data exchange and administrative workflows directly with the DataServ platform. The API suite supports two primary operational domains:

• User Management & Identity Lifecycle (/v2/users): Programmatically automate user onboarding, updates, deactivation, security group assignments, organization structure permissions, and audit logging by connecting upstream identity providers (IdP/IAM), HR systems, or custom internal tools via client-managed middleware.

• Transactional & Financial Data (/v1): Automate the exchange of invoices, purchase orders, receipts, vendor records, payment confirmations, and general ledger coding between DataServ and your ERP or accounting system.

Step 1: Prerequisites and Access

• API Key Management Access: API Key Management is available out of the box for all client environments. To generate and manage API keys, an administrator must have the API Management security group assigned to their user profile in DataServ.

• User Management & General API Usage: Fully self-service. Administrators can immediately generate keys within the DataServ portal and configure integration workflows.

• ERP Data Integration Migrations: If your organization currently exchanges transactional data (invoices, POs, vendors) via SFTP batch flat files and plans to migrate to real-time API integrations, please coordinate with your Client Success Account Manager (CSAM) to schedule migration and validation testing.

Step 2: Generating an API Key in DataServ

Visibility vs. permissions

Any user who has Configuration access will see the API Key Management page in the left-hand menu. However, to work with keys and interact with the API, the user must also be in the “API Management” security group.

If you don’t have the right permissions

If you navigate to Configuration > API Key Management and do not have the necessary access, you will see a message:

“Please contact your CSAM or support@dataserv.com to set up the API for your account.”

In that case:

1. Contact your internal admin or CSAM.

2. Request that you be added to the “API Management” security group, or ask them to manage keys on your behalf.

Generating a Key

API keys authenticate your external applications and middleware with the DataServ platform.

1. Log in to the DataServ portal with an account that has API Management permissions.

2. In the navigation menu, go to Configuration → API Key Management.

3. Click Generate New Key (or Add Key).

   

4. Enter a clear, descriptive name in the Description field. Examples:

   1. ERP A – AP Integration

   2. ERP B – Vendor Master Sync

   3. Data Warehouse – Invoice Extracts

      

5. After you create the key, the system will display:

   • The Key ID

   • The Secret

     

!!!!Important – save these credentials immediately!!!

• Copy and securely store both the Key ID and the Secret as soon as they are displayed.

• This is the only time you will see the Secret in the UI.

• For security reasons, the Secret cannot be viewed again later. If it is lost, you will need to create a new key.

  We strongly recommend storing these values in a secure secrets manager or password vault, and providing them to your development team using your internal secure channels.

Viewing or revoking keys

From the API Key Management page, users in the “API Management” security group can:

• View existing API keys and their names and IDs

• Revoke keys that are no longer needed or that may have been compromised

Note:

• You can see that a key exists and view its Name and Key ID, but you cannot see the Secret again after initial creation.

• If you lose the Secret or suspect it is exposed, revoke that key and create a new one.

We recommend:

• Using separate keys per integration (and per ERP where appropriate).

• Removing keys immediately when an integration is retired or a credential might be exposed.

Step 3: API Key Best Practices

• Use Purpose-Specific Naming: Name your API keys according to their specific application, function, and environment. Examples:

  • Identity Sync – Okta / HR Middleware (Production)

  • User Provisioning – Entra ID / Logic Apps (Dev)

  • ERP Integration – SAP S/4HANA AP

  • Data Warehouse – Invoice Extracts

• Segregate Workflows Across Separate Keys: We strongly recommend generating separate API keys for distinct integration functions (for example, keeping User Management identity keys separate from financial/ERP integration keys). This isolates permissions, simplifies auditing, and allows seamless credential rotation without cross-service downtime.

• Secure Storage: Store Client Secrets in an enterprise secrets manager (e.g., Azure Key Vault, AWS Secrets Manager, HashiCorp Vault) rather than hardcoding them in scripts.

Step 4: Authentication & Bearer Tokens

DataServ External APIs use OAuth 2.0 client credentials authentication:

1. Send a POST request to the /v1/token endpoint containing your client_id and client_secret.

2. The endpoint returns a JSON response containing an access_token (Bearer token) and its expiration time.

3. Cache the token within your application or middleware until expiration.

4. Include the token in the Authorization header of all subsequent API requests:

Authorization: Bearer <your_access_token>

Step 5: Interactive API Documentation (Swagger)

Comprehensive API endpoint specifications, interactive request/response schemas, JSON payload models, and HTTP response codes are maintained in the live API Documentation portal:

https://solution.dataserv.us/docs/

Key Endpoint Groups:

• Authentication:

  • Token – Generate OAuth 2.0 Bearer tokens using Client ID and Secret.

• User Management (/v2/users):

  • Users – Create, retrieve, update, deactivate, reactivate, and delete user accounts.

  • Security Groups & Org Structure – Programmatically manage role assignments and organization hierarchy access.

  • Activity & Audit – Query administrative change logs and user account history.

• Transactional & Master Data (/v1):

  • Extract – Retrieve processed invoice header/line data and image assets.

  • GL Code - Ingest general ledger codes data.

  • Payment – Ingest payment confirmations, remittance, and check data.

  • Purchase Order & Receipt – Ingest PO and receipt records for touchless AutoVouch matching.

  • Validation – Ingest confirmation of receipt of processed invoice data.

  • Vendor – Ingest and maintain vendor master records.

Step 6: Integration Architecture & Developer Responsibilities

DataServ External APIs are RESTful and tool-agnostic, allowing your development or integration team to connect any enterprise system using your preferred integration approach:

1. Middleware / iPaaS Configuration: Clients configure the integration layer (e.g., MuleSoft, Boomi, Workato, Azure Logic Apps, AWS Lambda, or custom service scripts) to orchestrate data movement between internal systems and DataServ endpoints.

2. Identity & User Provisioning Pattern: For user automation, your middleware queries your upstream IdP/IAM (e.g., Okta, Microsoft Entra ID) or HRIS on a schedule or event trigger, formats the payload according to DataServ’s JSON schemas, and calls the /v2/users endpoints.

3. Payload Transformation & Validation: The middleware is responsible for field mapping, handling DataServ standard response codes (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found), and managing automated retries for transient network issues.

Need Assistance?

• For technical endpoint schemas and test payloads, visit https://solution.dataserv.us/docs/.

• For questions regarding permissions or ERP integration migrations, please submit a request via the DataServ Help Center or reach out to your Client Success Account Manager