How to integrate

Integration examples for building lead scanning applications and lead export tools using the Swapcard Leads API.

This guide provides step-by-step integration examples for two common use cases:

1. Lead Scanning Application - Build an app that allows exhibitors to scan attendee badges at events
2. Lead Export Integration - Create a tool to export and sync lead data with external CRM systems

Integration: Lead Scanning Application

This example demonstrates how to build a lead scanning application that allows exhibitors to scan attendee badges during events.

Step 1: API Key Management

First, implement a secure way to collect and store the API key from your users.

Security Best Practice

Never store API keys in client-side code or expose them in web applications. Always store them securely on your server.

Implementation Steps:

1. Create a settings/configuration page in your app
2. Provide a secure input field for the API key
3. Store the key encrypted in your database or secure storage
4. Validate the key by making a test API call

Step 2: List Available Exhibitor Booths

Before scanning badges, users need to select which exhibitor booth they're representing. Use the myExhibitors query to retrieve all booths the user has access to.

cURL

curl -X POST \
  https://developer.swapcard.com/exhibitor/graphql \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query myExhibitors($cursor: CursorPaginationInput) { myExhibitors(cursor: $cursor) { pageInfo { hasNextPage endCursor } nodes { id name events { nodes { id title } } } } }",
    "variables": {
      "cursor": {
        "first": 100
      }
    }
  }'

Node.JS

const query = `
  query myExhibitors($cursor: CursorPaginationInput) {
    myExhibitors(cursor: $cursor) {
      pageInfo {
        hasNextPage
        endCursor
      }
      nodes {
        id
        name
        events {
          nodes {
            id
            title
          }
        }
      }
    }
  }
`;

async function getMyExhibitors(apiKey) {
  const response = await fetch('https://developer.swapcard.com/exhibitor/graphql', {
    method: 'POST',
    headers: {
      'Authorization': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: query,
      variables: {
        cursor: { first: 100 }
      }
    })
  });
  
  return await response.json();
}

PHP

<?php
$query = '
  query myExhibitors($cursor: CursorPaginationInput) {
    myExhibitors(cursor: $cursor) {
      pageInfo {
        hasNextPage
        endCursor
      }
      nodes {
        id
        name
        events {
          nodes {
            id
            title
          }
        }
      }
    }
  }
';

function getMyExhibitors($apiKey) {
    $data = json_encode([
        'query' => $query,
        'variables' => [
            'cursor' => ['first' => 100]
        ]
    ]);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://developer.swapcard.com/exhibitor/graphql');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: ' . $apiKey,
        'Content-Type: application/json'
    ]);

    $result = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($result, true);
}
?>

Python

import requests
import json

def get_my_exhibitors(api_key):
    query = """
    query myExhibitors($cursor: CursorPaginationInput) {
        myExhibitors(cursor: $cursor) {
            pageInfo {
                hasNextPage
                endCursor
            }
            nodes {
                id
                name
                events {
                    nodes {
                        id
                        title
                    }
                }
            }
        }
    }
    """
    
    headers = {
        'Authorization': api_key,
        'Content-Type': 'application/json'
    }
    
    payload = {
        'query': query,
        'variables': {
            'cursor': {'first': 100}
        }
    }
    
    response = requests.post(
        'https://developer.swapcard.com/exhibitor/graphql',
        headers=headers,
        json=payload
    )
    
    return response.json()

Response Example:

{
  "data": {
    "myExhibitors": {
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "eyJpZCI6IjEyMzQ1In0="
      },
      "nodes": [
        {
          "id": "RXhoaWJpdG9yXzU5NTIx",
          "name": "Tech Solutions Booth",
          "events": {
            "nodes": [
              {
                "id": "RXZlbnRfMjg1NzM=",
                "title": "Tech Conference 2025"
              }
            ]
          }
        }
      ]
    }
  }
}

Step 3: Scan Badges Implementation

Implement the badge scanning functionality using the scanBadges mutation. This supports both single scans and batch scanning for offline mode.

cURL

curl -X POST \
  https://developer.swapcard.com/exhibitor/graphql \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation scanBadges($input: ScanBadgesInput!) { scanBadges(input: $input) { badges { errorCode connection { id rating note target { __typename ... on PersonInterface { firstName lastName jobTitle email organization } } } } } }",
    "variables": {
      "input": {
        "eventId": "RXZlbnRfMjg1NzM=",
        "exhibitorId": "RXhoaWJpdG9yXzU5NTIx",
        "badges": [
          {
            "code": "BADGE_QR_CODE_123",
            "rating": 5,
            "note": "Very interested in our product"
          }
        ]
      }
    }
  }'

Node.JS

const scanBadgesMutation = `
  mutation scanBadges($input: ScanBadgesInput!) {
    scanBadges(input: $input) {
      badges {
        errorCode
        connection {
          id
          rating
          note
          target {
            __typename
            ... on PersonInterface {
              firstName
              lastName
              jobTitle
              email
              organization
            }
          }
        }
      }
    }
  }
`;

async function scanBadges(apiKey, eventId, exhibitorId, badges) {
  const response = await fetch('https://developer.swapcard.com/exhibitor/graphql', {
    method: 'POST',
    headers: {
      'Authorization': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: scanBadgesMutation,
      variables: {
        input: {
          eventId: eventId,
          exhibitorId: exhibitorId,
          badges: badges
        }
      }
    })
  });
  
  return await response.json();
}

// Example usage for single badge scan
const singleBadgeResult = await scanBadges(
  'YOUR_API_KEY',
  'RXZlbnRfMjg1NzM=',
  'RXhoaWJpdG9yXzU5NTIx',
  [
    {
      code: 'BADGE_QR_CODE_123',
      rating: 5,
      note: 'Very interested in our product'
    }
  ]
);

// Example usage for batch scan (offline mode)
const batchScanResult = await scanBadges(
  'YOUR_API_KEY',
  'RXZlbnRfMjg1NzM=',
  'RXhoaWJpdG9yXzU5NTIx',
  [
    { code: 'BADGE_001', rating: 4, note: 'Interested in demo' },
    { code: 'BADGE_002', rating: 5, note: 'Hot lead - follow up ASAP' },
    { code: 'BADGE_003', rating: 3, note: 'General interest' }
  ]
);

PHP

<?php
$scanBadgesQuery = '
  mutation scanBadges($input: ScanBadgesInput!) {
    scanBadges(input: $input) {
      badges {
        errorCode
        connection {
          id
          rating
          note
          target {
            __typename
            ... on PersonInterface {
              firstName
              lastName
              jobTitle
              email
              organization
            }
          }
        }
      }
    }
  }
';

function scanBadges($apiKey, $eventId, $exhibitorId, $badges) {
    $data = json_encode([
        'query' => $scanBadgesQuery,
        'variables' => [
            'input' => [
                'eventId' => $eventId,
                'exhibitorId' => $exhibitorId,
                'badges' => $badges
            ]
        ]
    ]);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://developer.swapcard.com/exhibitor/graphql');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: ' . $apiKey,
        'Content-Type: application/json'
    ]);

    $result = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($result, true);
}

// Example usage
$badges = [
    [
        'code' => 'BADGE_QR_CODE_123',
        'rating' => 5,
        'note' => 'Very interested in our product'
    ]
];

$result = scanBadges('YOUR_API_KEY', 'RXZlbnRfMjg1NzM=', 'RXhoaWJpdG9yXzU5NTIx', $badges);
?>

Python

import requests
import json

def scan_badges(api_key, event_id, exhibitor_id, badges):
    query = """
    mutation scanBadges($input: ScanBadgesInput!) {
        scanBadges(input: $input) {
            badges {
                errorCode
                connection {
                    id
                    rating
                    note
                    target {
                        __typename
                        ... on PersonInterface {
                            firstName
                            lastName
                            jobTitle
                            email
                            organization
                        }
                    }
                }
            }
        }
    }
    """
    
    headers = {
        'Authorization': api_key,
        'Content-Type': 'application/json'
    }
    
    payload = {
        'query': query,
        'variables': {
            'input': {
                'eventId': event_id,
                'exhibitorId': exhibitor_id,
                'badges': badges
            }
        }
    }
    
    response = requests.post(
        'https://developer.swapcard.com/exhibitor/graphql',
        headers=headers,
        json=payload
    )
    
    return response.json()

# Example usage for single badge scan
single_badge = [{
    'code': 'BADGE_QR_CODE_123',
    'rating': 5,
    'note': 'Very interested in our product'
}]

result = scan_badges('YOUR_API_KEY', 'RXZlbnRfMjg1NzM=', 'RXhoaWJpdG9yXzU5NTIx', single_badge)

# Example usage for batch scan (offline mode)
batch_badges = [
    {'code': 'BADGE_001', 'rating': 4, 'note': 'Interested in demo'},
    {'code': 'BADGE_002', 'rating': 5, 'note': 'Hot lead - follow up ASAP'},
    {'code': 'BADGE_003', 'rating': 3, 'note': 'General interest'}
]

batch_result = scan_badges('YOUR_API_KEY', 'RXZlbnRfMjg1NzM=', 'RXhoaWJpdG9yXzU5NTIx', batch_badges)

Response Example:

{
  "data": {
    "scanBadges": {
      "badges": [
        {
          "errorCode": null,
          "connection": {
            "id": "Q29ubmVjdGlvbl8xMTYzNDE=",
            "rating": 5,
            "note": "Very interested in our product",
            "target": {
              "__typename": "User",
              "firstName": "John",
              "lastName": "Doe",
              "jobTitle": "CTO",
              "email": "john.doe@example.com",
              "organization": "Tech Corp"
            }
          }
        }
      ]
    }
  }
}

Integration: Lead Export Integration

This example shows how to build a lead export tool that synchronizes lead data with external CRM systems or exports data for analysis.

Step 1: API Key Management

Follow the same secure API key management approach as described in Integration Example 1.

Step 2: List Available Exhibitor Booths

Use the same myExhibitors query implementation from Integration Example 1 to let users select which booths to export leads from.

Step 3: Export Leads Data

Use the myLeads query to retrieve all leads for a specific exhibitor booth and event.

cURL

curl -X POST \
  https://developer.swapcard.com/exhibitor/graphql \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query myLeads($eventId: ID!, $exhibitorId: ID!) { leads(eventId: $eventId, exhibitorId: $exhibitorId) { contacts { pageInfo { endCursor hasNextPage } nodes { id connectedAtEvent { id title } connectedAt isScanned rating note owner { id email firstName lastName jobTitle organization } target { ... on Contact { id email firstName lastName jobTitle organization } ... on User { id email firstName lastName jobTitle organization } } customFields { __typename ... on SelectField { id value definition { name id } } ... on TextField { id value definition { name } } } } } } }",
    "variables": {
      "eventId": "RXZlbnRfMjg1NzM=",
      "exhibitorId": "RXhoaWJpdG9yXzU5NTIx"
    }
  }'

Node.JS

const myLeadsQuery = `
  query myLeads($eventId: ID!, $exhibitorId: ID!) {
    leads(eventId: $eventId, exhibitorId: $exhibitorId) {
      contacts {
        pageInfo {
          endCursor
          hasNextPage
        }
        nodes {
          id
          connectedAtEvent {
            id
            title
          }
          connectedAt
          isScanned
          rating
          note
          owner {
            id
            email
            firstName
            lastName
            jobTitle
            organization
          }
          target {
            ... on Contact {
              id
              email
              firstName
              lastName
              jobTitle
              organization
            }
            ... on User {
              id
              email
              firstName
              lastName
              jobTitle
              organization
            }
          }
          customFields {
            __typename
            ... on SelectField {
              id
              value
              definition {
                name
                id
              }
            }
            ... on TextField {
              id
              value
              definition {
                name
              }
            }
          }
        }
      }
    }
  }
`;

async function exportLeads(apiKey, eventId, exhibitorId) {
  const response = await fetch('https://developer.swapcard.com/exhibitor/graphql', {
    method: 'POST',
    headers: {
      'Authorization': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: myLeadsQuery,
      variables: {
        eventId: eventId,
        exhibitorId: exhibitorId
      }
    })
  });
  
  const result = await response.json();
  return result;
}

// Example usage
const leads = await exportLeads('YOUR_API_KEY', 'RXZlbnRfMjg1NzM=', 'RXhoaWJpdG9yXzU5NTIx');

// Process and format leads for your CRM
function formatLeadsForCRM(leads) {
  return leads.data.leads.contacts.nodes.map(lead => ({
    id: lead.id,
    firstName: lead.target.firstName,
    lastName: lead.target.lastName,
    email: lead.target.email,
    company: lead.target.organization,
    jobTitle: lead.target.jobTitle,
    rating: lead.rating,
    notes: lead.note,
    scannedAt: lead.connectedAt,
    event: lead.connectedAtEvent.title,
    customFields: lead.customFields.reduce((acc, field) => {
      acc[field.definition.name] = field.value;
      return acc;
    }, {})
  }));
}

const formattedLeads = formatLeadsForCRM(leads);

PHP

<?php
$myLeadsQuery = '
  query myLeads($eventId: ID!, $exhibitorId: ID!) {
    leads(eventId: $eventId, exhibitorId: $exhibitorId) {
      contacts {
        pageInfo {
          endCursor
          hasNextPage
        }
        nodes {
          id
          connectedAtEvent {
            id
            title
          }
          connectedAt
          isScanned
          rating
          note
          owner {
            id
            email
            firstName
            lastName
            jobTitle
            organization
          }
          target {
            ... on Contact {
              id
              email
              firstName
              lastName
              jobTitle
              organization
            }
            ... on User {
              id
              email
              firstName
              lastName
              jobTitle
              organization
            }
          }
          customFields {
            __typename
            ... on SelectField {
              id
              value
              definition {
                name
                id
              }
            }
            ... on TextField {
              id
              value
              definition {
                name
              }
            }
          }
        }
      }
    }
  }
';

function exportLeads($apiKey, $eventId, $exhibitorId) {
    $data = json_encode([
        'query' => $myLeadsQuery,
        'variables' => [
            'eventId' => $eventId,
            'exhibitorId' => $exhibitorId
        ]
    ]);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://developer.swapcard.com/exhibitor/graphql');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: ' . $apiKey,
        'Content-Type: application/json'
    ]);

    $result = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($result, true);
}

function formatLeadsForCRM($leads) {
    $formattedLeads = [];
    
    foreach ($leads['data']['leads']['contacts']['nodes'] as $lead) {
        $customFields = [];
        foreach ($lead['customFields'] as $field) {
            $customFields[$field['definition']['name']] = $field['value'];
        }
        
        $formattedLeads[] = [
            'id' => $lead['id'],
            'firstName' => $lead['target']['firstName'],
            'lastName' => $lead['target']['lastName'],
            'email' => $lead['target']['email'],
            'company' => $lead['target']['organization'],
            'jobTitle' => $lead['target']['jobTitle'],
            'rating' => $lead['rating'],
            'notes' => $lead['note'],
            'scannedAt' => $lead['connectedAt'],
            'event' => $lead['connectedAtEvent']['title'],
            'customFields' => $customFields
        ];
    }
    
    return $formattedLeads;
}

// Example usage
$leads = exportLeads('YOUR_API_KEY', 'RXZlbnRfMjg1NzM=', 'RXhoaWJpdG9yXzU5NTIx');
$formattedLeads = formatLeadsForCRM($leads);

// Export to CSV
function exportToCSV($leads, $filename) {
    $file = fopen($filename, 'w');
    
    if (!empty($leads)) {
        fputcsv($file, array_keys($leads[0]));
        foreach ($leads as $lead) {
            fputcsv($file, $lead);
        }
    }
    
    fclose($file);
}

exportToCSV($formattedLeads, 'leads_export.csv');
?>

Python

import requests
import json
import csv
from datetime import datetime

def export_leads(api_key, event_id, exhibitor_id):
    query = """
    query myLeads($eventId: ID!, $exhibitorId: ID!) {
        leads(eventId: $eventId, exhibitorId: $exhibitorId) {
            contacts {
                pageInfo {
                    endCursor
                    hasNextPage
                }
                nodes {
                    id
                    connectedAtEvent {
                        id
                        title
                    }
                    connectedAt
                    isScanned
                    rating
                    note
                    owner {
                        id
                        email
                        firstName
                        lastName
                        jobTitle
                        organization
                    }
                    target {
                        ... on Contact {
                            id
                            email
                            firstName
                            lastName
                            jobTitle
                            organization
                        }
                        ... on User {
                            id
                            email
                            firstName
                            lastName
                            jobTitle
                            organization
                        }
                    }
                    customFields {
                        __typename
                        ... on SelectField {
                            id
                            value
                            definition {
                                name
                                id
                            }
                        }
                        ... on TextField {
                            id
                            value
                            definition {
                                name
                            }
                        }
                    }
                }
            }
        }
    }
    """
    
    headers = {
        'Authorization': api_key,
        'Content-Type': 'application/json'
    }
    
    payload = {
        'query': query,
        'variables': {
            'eventId': event_id,
            'exhibitorId': exhibitor_id
        }
    }
    
    response = requests.post(
        'https://developer.swapcard.com/exhibitor/graphql',
        headers=headers,
        json=payload
    )
    
    return response.json()

def format_leads_for_crm(leads):
    formatted_leads = []
    
    for lead in leads['data']['leads']['contacts']['nodes']:
        custom_fields = {}
        for field in lead['customFields']:
            custom_fields[field['definition']['name']] = field['value']
        
        formatted_leads.append({
            'id': lead['id'],
            'firstName': lead['target']['firstName'],
            'lastName': lead['target']['lastName'],
            'email': lead['target']['email'],
            'company': lead['target']['organization'],
            'jobTitle': lead['target']['jobTitle'],
            'rating': lead['rating'],
            'notes': lead['note'],
            'scannedAt': lead['connectedAt'],
            'event': lead['connectedAtEvent']['title'],
            'customFields': custom_fields
        })
    
    return formatted_leads

def export_to_csv(leads, filename):
    if not leads:
        return
    
    with open(filename, 'w', newline='', encoding='utf-8') as csvfile:
        writer = csv.DictWriter(csvfile, fieldnames=leads[0].keys())
        writer.writeheader()
        writer.writerows(leads)

# Example usage
leads = export_leads('YOUR_API_KEY', 'RXZlbnRfMjg1NzM=', 'RXhoaWJpdG9yXzU5NTIx')
formatted_leads = format_leads_for_crm(leads)

# Export to CSV
timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
filename = f'leads_export_{timestamp}.csv'
export_to_csv(formatted_leads, filename)

print(f"Exported {len(formatted_leads)} leads to {filename}")

# Example: Send to CRM webhook
def send_to_crm(leads, webhook_url):
    for lead in leads:
        response = requests.post(webhook_url, json=lead)
        print(f"Sent lead {lead['id']} to CRM: {response.status_code}")

# send_to_crm(formatted_leads, 'https://your-crm-webhook.com/leads')

Response Example:

{
  "data": {
    "leads": {
      "contacts": {
        "pageInfo": {
          "endCursor": "WyIyMDI1LTA5LTAzVDEzOjI4OjMzLjAwMFoiLDExNjM0MV0=",
          "hasNextPage": false
        },
        "nodes": [
          {
            "id": "Q29ubmVjdGlvbl8xMTYzNDE=",
            "connectedAtEvent": {
              "id": "RXZlbnRfMjg1NzM=",
              "title": "Tech Conference 2025"
            },
            "connectedAt": "2025-09-03 15:28:33",
            "isScanned": true,
            "rating": 5,
            "note": "Very interested in our cloud solution",
            "owner": {
              "id": "VXNlcl8yNDExNg==",
              "email": "exhibitor@techcorp.com",
              "firstName": "Sarah",
              "lastName": "Johnson",
              "jobTitle": "Sales Manager",
              "organization": "Tech Corp"
            },
            "target": {
              "id": "VXNlcl8xNDc3MTg=",
              "email": "john.doe@example.com",
              "firstName": "John",
              "lastName": "Doe",
              "jobTitle": "CTO",
              "organization": "Example Inc"
            },
            "customFields": [
              {
                "__typename": "SelectField",
                "id": "RmllbGRWYWx1ZV8zMzg3ODA=",
                "value": "yes",
                "definition": {
                  "name": "Interested in Cloud Solution?",
                  "id": "RmllbGREZWZpbml0aW9uXzI0NzYyNg=="
                }
              }
            ]
          }
        ]
      }
    }
  }
}