API - Getting Started Guide

Welcome to the manage.discoveryapp.io API V1! This guide will walk you through the initial steps to set up and start using the API to interact with your Discovery account programmatically.

Prerequisites

Before you begin, ensure you have:

  • A registered account on manage.discoveryapp.io.
  • A stable internet connection.
  • A basic understanding of REST APIs and how to make HTTP requests.

Step 1: Log in to Discovery

  1. Open your browser and navigate to manage.discoveryapp.io.
  2. Enter your email and password to log in. If you don’t have an account, click "Sign Up" to create one and verify your email address.

Step 2: Access Your Profile

  1. Once logged in, locate your profile image in the top right corner of the dashboard.
  2. Click on your profile image to open the dropdown menu.
  3. Select "My Profile" from the dropdown menu to access your profile settings.

Step 3: Navigate to the V1 API Tab

  1. In the profile settings, find and click on the "V1 API" tab.
  2. This will take you to the API token management page: https://manage.discoveryapp.io/api-tokens.

Step 4: Create a New API Token

  1. On the API token management page, click the "New Token" button.
  2. Provide a nickname for your API token (e.g., "VendorInvoiceAPI"). This helps you identify the token’s purpose later, and you can change the nickname at any time.
  3. Choose your token's access level: Read & Write or Read Only.*
  4. After creating the token, copy it immediately and store it securely.

Step 5: Go to the API Playground

  1. Navigate to the API Playground by visiting https://manage.discoveryapp.io/api.
  2. The Playground provides an interactive environment to test API endpoints without writing code.

Step 6: Authorize Your API Token in the Playground

  1. In the API Playground, locate the "Authorize" button in the top right corner and click it.

  1. A dialog box will appear prompting you to enter your API key.
  2. Paste the API token you copied in Step 4 into the input field and confirm to authorize.

Step 7: Test Your First API Call

  1. In the Playground, find the endpoint for gathered vendor invoice files: /api/v1/gathered-vendor-invoice-files.
  2. Click on the endpoint to expand its details.
  3. Click the "Try it Now" button to execute the API call.

  1. Review the response to ensure the call was successful. You should see a list of your gathered vendor invoice files if the token and endpoint are valid.

Best Practices for API Token Management

  • Keep Your Token Secure: Never share your API token publicly or store it in unsecured locations like public repositories.
  • Rotate Tokens Regularly: Periodically generate new tokens and revoke old ones to maintain security.
  • Use Descriptive Nicknames: Assign meaningful names to your tokens to easily track their usage.
  • Monitor Usage: Check the API token management page to monitor token activity and revoke any suspicious tokens.

Next Steps

  • Explore other API endpoints in the Playground to understand the full range of capabilities.
  • Integrate the API into your application using your preferred programming language. Refer to the API documentation for detailed endpoint descriptions and request/response formats.
  • If you encounter issues, reach out to support via the Discovery dashboard or email [email protected].

*Read-Only API Tokens

When creating a token, you have the option to mark it as read-only. A read-only token can fetch data from any Discovery endpoint but is blocked from making any changes.

What you can do with a read-only token:

  • Retrieve records (locations, services, vendors, invoices, pickups, etc.)
  • Search and filter data
  • Export information to external tools or dashboards

What you cannot do with a read-only token:

  • Create new records (POST)
  • Update existing records (PATCH)
  • Delete or archive records (DELETE)

If a read-only token is used to attempt a write operation, the API will return a 403 Forbidden  response.

When to use a read-only token:

Use a read-only token any time you're sharing API access with a third-party reporting tool, a BI dashboard, or a developer who only needs to pull data. It limits the blast radius if the token is ever exposed — an attacker with a read-only token can't modify or delete your data.

Note: Like all tokens, a read-only token is displayed only once at the time of creation. Copy it to a secure location before closing the dialog.

If you have additional questions or need more in depth information, please feel free to send us a message using the help beacon in the lower right-hand corner.