> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearline.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Get up and running with the ClearLine API in 5 minutes

This guide walks you through making your first successful API call using a POS integration workflow. You'll authenticate, start an interaction, and be ready to process transactions.

<Info>
  **New to authentication?** Check out our [Authentication Guide](/api-reference/authentication/introduction) to understand OAuth flows, choose the right method, and learn about security best practices.
</Info>

## Prerequisites

Before you begin, make sure you have:

* A ClearLine account (Demo or Production environment)
* API credentials (Client ID and Client Secret)
* A registered POS terminal ID
* A location ID from your POS system

<Note>
  **Don't have credentials?** Contact your ClearLine representative or [support@clearline.me](mailto:support@clearline.me) to get started.
</Note>

***

## Step 1: Get Your Access Token

Authenticate using the [Client Credentials flow](/api-reference/authentication/introduction#get-your-access-token) to get an access token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://logindemo.clearline.me/connect/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
    -d "grant_type=client_credentials&scope=pos_integration"
  ```

  ```javascript JavaScript theme={null}
  const credentials = btoa("YOUR_CLIENT_ID:YOUR_CLIENT_SECRET");

  const response = await fetch("https://logindemo.clearline.me/connect/token", {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${credentials}`,
    },
    body: "grant_type=client_credentials&scope=pos_integration",
  });

  const data = await response.json();
  const accessToken = data.access_token;
  console.log("Access Token:", accessToken);
  ```
</CodeGroup>

### Response

<ResponseField name="access_token" type="string" required>
  JWT token for authenticating API requests. Include this in the `Authorization:
        Bearer {token}` header for all subsequent API calls. Example: `eyJhbGciOiJSUzI1NiIsImtpZCI6Ij...`
</ResponseField>

<ResponseField name="token_type" type="string" required>
  Token type, always `Bearer` for OAuth2 tokens.
</ResponseField>

<ResponseField name="expires_in" type="integer" required>
  Token lifetime in seconds. Default is `3600` (1 hour). Request a new token before expiration.
</ResponseField>

<ResponseField name="scope" type="string" required>
  The granted OAuth scope. Should match your requested scope: `pos_integration`
</ResponseField>

<Tip>
  **Save this token!** You'll use it in all subsequent API calls. It's valid for 1 hour (3600 seconds).
</Tip>

<Info>
  For other authentication methods (user apps, mobile apps, etc.), see the [complete Authentication Guide](/api-reference/authentication/introduction).
</Info>

***

## Step 2: Start Your First Interaction

Now make your first API call to start a customer interaction:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://public-api-demo.clearline.me/pos/clover/startInteraction \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -d '{
      "terminalID": "YOUR_TERMINAL_ID",
      "posLocationId": "YOUR_LOCATION_ID"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://public-api-demo.clearline.me/pos/clover/startInteraction",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${accessToken}`,
      },
      body: JSON.stringify({
        terminalID: "YOUR_TERMINAL_ID",
        posLocationId: "YOUR_LOCATION_ID",
      }),
    }
  );

  const data = await response.json();
  const sessionId = data.data.sessionId;
  console.log("Session ID:", sessionId);
  ```
</CodeGroup>

### Response

<ResponseField name="data" type="object" required>
  Container object for the interaction response data.

  <Expandable title="data properties">
    <ResponseField name="terminalId" type="string" required>
      Echoes back your terminal ID for confirmation. Should match your request.
    </ResponseField>

    <ResponseField name="posLocationId" type="string" required>
      Echoes back your location ID for confirmation. Should match your request.
    </ResponseField>

    <ResponseField name="sessionId" type="string" required>
      **Important:** Use this session ID when submitting transaction data. It links the customer interaction to the transaction.

      Example: `9a19a987-7e0b-4bc2-8126-e92e3c6c7860`
    </ResponseField>

    <ResponseField name="posStatus" type="string" required>
      Status of the interaction request. Should be `Accepted` for successful interactions.

      Possible values: `Accepted`, `Rejected`, `Error`
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  **Terminal Not Registered?** If you get a 404 error, your terminal ID needs to be registered in the ClearLine Admin Portal first.
</Warning>

***

## Next Steps

Now that you've made your first successful API call, you can:

<CardGroup cols={2}>
  <Card title="Submit a Transaction" icon="receipt" href="/api-reference/transactions">
    Send transaction data using your sessionId
  </Card>

  <Card title="Explore All Endpoints" icon="rectangle-terminal" href="/api-reference/overview">
    Browse the complete API reference
  </Card>

  <Card title="Integration Workflows" icon="diagram-project" href="/api/pos-integration">
    Learn complete integration patterns
  </Card>

  <Card title="Test Environments" icon="server" href="/api/environments">
    Configure different environments
  </Card>
</CardGroup>

***

## Common Issues

<AccordionGroup>
  <Accordion title="401 Unauthorized Error">
    **Cause:** Invalid or expired access token **Solution:** - Verify your Client ID and Client Secret are correct - Check that you're using the right environment (demo vs production) - Request a new access token if it expired
  </Accordion>

  {" "}

  <Accordion title="404 Terminal Not Found">
    **Cause:** Terminal ID not registered in ClearLine **Solution:** - Log into the ClearLine Admin Portal - Navigate to Terminals - Register your terminal ID

    * Wait a few minutes for sync, then try again
  </Accordion>

  <Accordion title="Connection Timeout">
    **Cause:** Network issues or wrong environment URL **Solution:** - Verify you're using the correct base URL for your environment - Check your network firewall settings - Try the demo environment first: `public-api-demo.clearline.me`
  </Accordion>
</AccordionGroup>

***

## Complete Example

Here's a complete working example that authenticates and starts an interaction:

<CodeGroup>
  ```javascript Complete Example theme={null}
  async function quickStart() {
    // Step 1: Authenticate
    const credentials = btoa('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET');
    
    const authResponse = await fetch(
      'https://logindemo.clearline.me/connect/token',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Authorization': `Basic ${credentials}`
        },
        body: 'grant_type=client_credentials&scope=pos_integration'
      }
    );
    
    const authData = await authResponse.json();
    const accessToken = authData.access_token;
    
    console.log('✓ Authenticated successfully');
    
    // Step 2: Start Interaction
    const interactionResponse = await fetch(
      'https://public-api-demo.clearline.me/pos/clover/startInteraction',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify({
          terminalID: 'YOUR_TERMINAL_ID',
          posLocationId: 'YOUR_LOCATION_ID'
        })
      }
    );
    
    const interactionData = await interactionResponse.json();
    const sessionId = interactionData.data.sessionId;
    
    console.log('✓ Session started:', sessionId);
    console.log('✓ Ready to process transactions!');
    
    return { accessToken, sessionId };
  }

  // Run it
  quickStart().catch(console.error);
  ```

  ```bash cURL Script theme={null}
  #!/bin/bash

  # Configuration
  CLIENT_ID="YOUR_CLIENT_ID"
  CLIENT_SECRET="YOUR_CLIENT_SECRET"
  TERMINAL_ID="YOUR_TERMINAL_ID"
  LOCATION_ID="YOUR_LOCATION_ID"

  # Step 1: Get Access Token
  echo "Authenticating..."
  TOKEN_RESPONSE=$(curl -s -X POST https://logindemo.clearline.me/connect/token \
    -u "$CLIENT_ID:$CLIENT_SECRET" \
    -d "grant_type=client_credentials&scope=pos_integration")

  ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)

  if [ -z "$ACCESS_TOKEN" ]; then
    echo "❌ Authentication failed"
    exit 1
  fi

  echo "✓ Authenticated successfully"

  # Step 2: Start Interaction
  echo "Starting interaction..."
  SESSION_RESPONSE=$(curl -s -X POST https://public-api-demo.clearline.me/pos/clover/startInteraction \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d "{\"terminalID\":\"$TERMINAL_ID\",\"posLocationId\":\"$LOCATION_ID\"}")

  SESSION_ID=$(echo $SESSION_RESPONSE | grep -o '"sessionId":"[^"]*' | cut -d'"' -f4)

  if [ -z "$SESSION_ID" ]; then
    echo "❌ Failed to start interaction"
    echo $SESSION_RESPONSE
    exit 1
  fi

  echo "✓ Session started: $SESSION_ID"
  echo "✓ Ready to process transactions!"
  ```
</CodeGroup>

***

## What's Next?

<Steps>
  <Step title="Send a Transaction">
    Use your `sessionId` to submit transaction data [View Transaction Endpoints
    →](/api-reference/transactions)
  </Step>

  <Step title="Implement Error Handling">
    Add retry logic and proper error handling [View Error Handling Guide
    →](/pos-integration)
  </Step>

  <Step title="Go to Production">
    Switch to production URLs and credentials [View Environments
    →](/api-reference/environments)
  </Step>
</Steps>

<Tip>
  **Need Help?** Check out the [complete transaction workflow
  guide](/pos-integration/post-purchase-transaction-to-cmc) for detailed implementation steps with diagrams and best practices.
</Tip>