Articles in this section

See more

API-Setup Guide for Admins and Developers

Avatar
DataServ Support Staff
  • Updated
Follow

The DataServ API provides a modern, secure way to integrate your systems with DataServ. It supports real-time or near real-time data exchange for invoices, vendors, purchase orders, and general ledger data, reducing manual file handling and format-related errors.

This article explains how to:

  • Request access to the API

  • Understand ERP and migration prerequisites

  • Enable and manage API access in DataServ

  • Create API keys

  • Access our Swagger documentation and start testing

All technical details (endpoints, request/response schemas, and examples) are published in our Swagger documentation, not in this article.

Who should use this guide

This guide is intended for:

  • DataServ administrators who manage configuration and integrations for your organization

  • Developers / IT teams who will build, maintain, or support integrations with DataServ

Prerequisites

Before you begin, ensure the following are true.

Platform and access prerequisites

  1. You have an active DataServ user account.

  2. Your organization has the DataServ API feature enabled by DataServ.

  3. You have access to Configuration in DataServ.

  4. To create and manage API keys, you have been granted the “API Management” security group.

If you are not sure about any of the above, contact your internal DataServ admin, your Client Success Account Manager (CSAM), or DataServ Support at support@dataserv.com.

ERP and integration prerequisites

  1. Organization Structure for your organization

    • Your organization must already be set up on the new Organization Structure feature within DataServ.

    • If you are not sure whether your ERP(s) is/are on the new Organization Structure, contact your CSAM or Support.

  2. How migration works for existing vs. new clients

    • Existing clients (already live on DataServ):

      • If you currently use a SFTP datafile batch process for a given ERP, that ERP must be fully migrated to the API.

      • For that ERP, you cannot:

        • keep some data flows on SFTP datafiles and

        • move only selected data (e.g., only invoices) to the API.

      • It is an all-or-nothing migration for each ERP:

        • Once you move an ERP to the API, the SFTP datafile batch process for that ERP will be turned off.

      • This change is handled as a migration project, coordinated between your team and DataServ.

    • New clients (implementing DataServ for the first time):

      • If you are a new client and choose to use the API, the API setup will be handled as part of your initial implementation / onboarding.

      • In this case, there is typically no SFTP datafile batch process to migrate away from for that ERP; instead, the API-based integration is set up from the start.

  3. Multiple ERP support

    • If you have multiple ERPs, you can migrate or implement them one at a time:

      • ERP A can be configured to use the API,

      • while ERP B (and others) can continue using the SFTP datafile batch process until you are ready to move those to the API.

    • The “all-or-nothing” rule applies per ERP, not across all ERPs in your organization.

  4. Client-side integration scripts / middleware

    • Your team will need to create or update scripts or integration logic on your side to act as an intermediary between your ERP and the DataServ API.

    • These scripts:

      • Extract data from your ERP

      • Transform it into the format expected by DataServ’s API

      • Send/receive it via the API endpoints

    • In many cases, you may already have similar scripts today that prepare datafiles for an existing SFTP process; those can often be adapted to call the API instead of generating SFTP files.

Step 1 – Request API access from DataServ

Any client-side user can request API enablement.

  1. Contact one of the following:

  2. In your request, specify that you would like to:

    • Enable the DataServ API for your organization

    • Identify:

      • Which ERP(s) you plan to use with the API

      • Whether your organization is already on the new Organization Structure feature

      • Whether you are an existing client (with a current SFTP-based integration) or a new client in implementation

  3. What DataServ will do:

    • For existing clients:

      • Confirm that you are on the new Organization Structure feature (or help you plan this if not yet done).

      • Plan and coordinate the migration project from your existing SFTP datafile batch process (for the selected ERP) to the API.

      • Align timing and cutover so that once the API is live and validated, the SFTP process for that ERP can be retired.

    • For new clients:

      • Incorporate the API into your initial implementation / onboarding for the selected ERP(s), rather than setting up SFTP first.

    • In both cases:

      • Enable the API feature for your account.

      • Notify your team (including IT) when the feature is enabled and ready for configuration.

      • Ensure the appropriate users receive access to:

        • Configuration > API Key Management, and

        • The Swagger documentation for your organization.

Once access is enabled and your integration approach is agreed, authorized users can proceed with the configuration steps below.

Step 2 – Access the API Key Management page

Once your organization has API access enabled:

  1. Sign in to DataServ (https://solution.dataserv.us/gandalf/#login)

  2. In the main navigation, go to: 
    Configuration > API Key Management

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.

Step 3 – Create and manage API keys (for admins)

Users in the “API Management” security group can create and manage API keys for their organization.

Creating a new API key

  1. Go to Configuration > API Key Management.

  2. Select the option to create a new API key.

  3. When prompted, provide a Name for the key:

    • This is the only field you need to fill out.

    • Use a clear, descriptive name so you can easily recognize what this key is used for later. Examples:

      • ERP A – AP Integration

      • ERP B – Vendor Master Sync

      • Data Warehouse – Invoice Extracts

  4. 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 4 – Obtain an access token (for developers)

The DataServ API uses an access-token-based approach to secure requests. At a high level, developers will:

  1. Use the API key / client credentials created in Step 3.

  2. Call the appropriate authentication endpoint to obtain an access token.

  3. Include that access token in the headers of subsequent API requests to DataServ.

Details such as:

  • The token endpoint URL

  • Required request parameters

  • Example request and response payloads

  • Token expiration and refresh behavior

are documented in the Swagger interface (see Step 5 below). Your developers should follow those examples exactly when implementing authentication.

Step 5 – Access and use Swagger

Swagger is the source of truth for:

  • Available endpoints

  • Request and response schemas

  • Authentication details

  • Example payloads

  • Error codes and status responses

Opening the Swagger documentation

Once your organization has API access enabled and you have the necessary permissions:

  1. Ensure you are:

    • Logged in with your DataServ account

    • A member of the “API Management” security group (to fully interact with the docs)

    • Go to Configuration > API Key Management and click on Visit Swagger Page.

Using Swagger

In Swagger, developers can:

  • Browse all available v1 endpoints

    • Token

      • Endpoints to obtain and refresh access tokens using your API credentials.

      • Required for authenticating all other API calls.

    • Extract API

      • Endpoints to retrieve data from DataServ for use in your downstream systems and reporting.

      • Typical use cases include pulling invoice- or payment-related information back into your ERP or data warehouse.

    • Payment API

      • Endpoints to send or receive information related to payments and payment activity associated with your invoices.

    • Purchase Order API

      • Endpoints to manage purchase order data exchanged between your ERP and DataServ, helping keep PO information aligned across systems.

    • Receipt API

      • Endpoints to work with receipts / goods receipts information that supports matching and validation of invoices.

    • Validation API

      • Endpoints to perform or retrieve validation-related data that supports your business rules, matching, and exception handling.

    • Vendor API

      • Endpoints to create, update, or synchronize vendor / supplier master data between your ERP and DataServ.

  • See the HTTP methods, URLs, and required parameters

  • View request and response schemas, including field names and formats

  • Use “Try it out” functionality (where available) to:

    • Send test requests to your environment

    • Confirm that authentication is working

    • Validate that requests and responses meet your integration needs

Swagger will also detail any:

  • Rate limits applied to requests

  • Standard error responses and status codes

  • Additional headers or conventions required

Developer responsibilities and integration pattern

Because the API connects to your ERP through your own integration layer, your development team is responsible for:

  • Building or adapting scripts / middleware that:

    • Extract data from your ERP

    • Transform that data into the payloads defined in Swagger

    • Call the relevant DataServ API endpoints and handle responses

  • Handling both directions of data flow where applicable:

    • Sending data from your ERP into DataServ (e.g., master data, transactions)

    • Consuming data from DataServ back into your systems (e.g., statuses, results)

If you already have scripts that format data for a SFTP-based process, those are often a good starting point—they can be updated to produce API requests instead of files.

Your development team should use Swagger as the authoritative reference when building or updating your scripts or middleware between your ERP and the DataServ API.

Best practices

  • Use least-privilege principles 
    Only grant “API Management” access to users who actually need to manage keys and interact with Swagger.

  • Separate credentials per ERP and integration 
    Use distinct API keys for each ERP and/or integration to simplify auditing and revocation.

  • Secure storage 
    Store API keys and tokens in a secure secrets manager or vault; never commit them to source control or share in plain text.

  • Plan your ERP-by-ERP rollout 
    Work with your CSAM to:

    • Confirm that your organization is on the new Organization Structure feature.

    • Decide, for each ERP, whether you’re:

      • Migrating from SFTP datafiles to API (existing clients), or

      • Implementing directly on API as part of onboarding (new clients).

Troubleshooting and support

You may encounter the following situations:

  • You don’t see “API Key Management” under Configuration

    • You likely don’t have Configuration access.

    • Contact your internal DataServ admin or your CSAM.

  • You see the pop-up: “Please contact your CSAM or support@dataserv.com to set up the API for your account.”

    • Your user is not in the “API Management” security group, or the API is not yet fully configured for your organization.

    • Contact your CSAM or support@dataserv.com and mention this message.

  • You can’t access Swagger or receive authorization errors

    • Confirm:

      • Your organization’s API feature is enabled

      • Your user has the “API Management” security group

      • You are using the correct Swagger URL and environment

    • Review the authentication examples in Swagger.

    • If issues persist, contact support@dataserv.com with:

      • A description of the error

      • The endpoint you are calling

      • Any relevant request IDs or timestamps

 

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk