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

# Integrations API

> Connect external systems with COR through the Integrations API for seamless data synchronization

The Integrations API is a dedicated service that acts as an intermediary between external systems and COR. It enables you to map external IDs from third-party services to COR entities, facilitating seamless data synchronization and workflow automation.

## Overview

The Integrations API provides a standardized way to:

* **Map external IDs** — Link entities from external systems (Salesforce, Jira, SAP, etc.) to their corresponding COR entities
* **Sync data bidirectionally** — Keep data consistent between COR and external platforms
* **Handle webhooks** — Process incoming events from external services and route updates accordingly
* **Track integration state** — Maintain a record of which entities are integrated and their sync status

## Architecture

```mermaid theme={null}
flowchart LR
    subgraph external [External Services]
        SF[Salesforce]
        JIRA[Jira]
        SAP[SAP]
        OTHER[Other Systems]
    end
    
    subgraph integrations [Integrations Domain]
        INTAPI[Integrations API]
        INTDB[(Integrations DB)]
    end
    
    subgraph cor [COR Platform]
        CORAPI[COR API]
        MAINDB[(Main DB)]
        WEB[Web App]
    end
    
    SF -->|external_id mapping| INTAPI
    JIRA -->|webhooks| INTAPI
    SAP -->|sync events| INTAPI
    OTHER --> INTAPI
    
    INTAPI <-->|CRUD operations| CORAPI
    INTAPI --> INTDB
    CORAPI --> MAINDB
    MAINDB --> WEB
```

## Base URL

All integration endpoints use the following base URL:

```
https://integrations.projectcor.com/
```

## Integration Flows

The Integrations API supports three types of data flows depending on your integration requirements:

<CardGroup cols={3}>
  <Card title="External → COR" icon="arrow-right">
    **Unidirectional inbound**

    Data flows from an external service into COR. Example: Creating projects in COR when opportunities are won in Salesforce.
  </Card>

  <Card title="COR → External" icon="arrow-left">
    **Unidirectional outbound**

    Data flows from COR to an external service. Example: Syncing time entries to an external billing system.
  </Card>

  <Card title="Bidirectional" icon="arrows-left-right">
    **Two-way sync**

    Full synchronization where changes in either system are reflected in the other. Example: Project updates synced between COR and Jira.
  </Card>
</CardGroup>

### Flow Selection

Choose your integration flow based on:

| Flow Type      | Use Case                               | Example                             |
| -------------- | -------------------------------------- | ----------------------------------- |
| External → COR | External system is the source of truth | CRM creates projects in COR         |
| COR → External | COR is the source of truth             | Time tracking synced to payroll     |
| Bidirectional  | Both systems need real-time updates    | Project management across platforms |

## Authentication

<Note>
  The Integrations API uses the **same authentication** as the main COR API. You can use the same Bearer token obtained from the COR authentication endpoints.
</Note>

All requests require a Bearer token in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json
```

Obtain your access token using one of the authentication methods from the main API:

* [Client Credentials](/api-reference/auth/jwt-authorization-by-client-credentials)
* [Authorization Code](/api-reference/auth/jwt-authorization-by-authorization-code)
* [User Credentials](/api-reference/auth/jwt-authorization-by-user-credentials)

## Required Fields

All integration endpoints require the `metadata.source` field to identify the external system:

```json theme={null}
{
  "metadata": {
    "source": "SALESFORCE"
  },
  "id": "external-entity-id-123",
  "name": "Entity Name",
  // ... other entity fields
}
```

<Warning>
  The `metadata.source` field is **required** in all integration requests. It identifies which external system the data originates from and is used to route webhooks and maintain integration mappings.
</Warning>

## Supported Integration Sources

The API supports the following integration sources:

<Accordion title="View all supported sources">
  | Source               | Description                       |
  | -------------------- | --------------------------------- |
  | `JIRA`               | Atlassian Jira project management |
  | `SALESFORCE`         | Salesforce CRM                    |
  | `ADVERTMIND`         | Advertmind platform               |
  | `QUICKBOOKS`         | QuickBooks accounting             |
  | `ZAPIER`             | Zapier automation                 |
  | `OKTA`               | Okta identity management          |
  | `MICROSOFT_DYNAMICS` | Microsoft Dynamics 365            |
  | `GITHUB`             | GitHub repository management      |
  | `MICROSOFT_TEAMS`    | Microsoft Teams                   |
  | `VBS`                | VBS system                        |
  | `SAP`                | SAP enterprise system             |
  | `GLOBANT`            | Globant platform                  |
</Accordion>

<Tip>
  Need a custom integration source? Contact the COR development team to request support for additional platforms.
</Tip>

## Available Entities

The Integrations API provides endpoints for managing the following entities:

| Entity                                                        | Operations                                  | Description                      |
| ------------------------------------------------------------- | ------------------------------------------- | -------------------------------- |
| [Brands](/api-reference/integrations/brands)                  | CREATE, UPDATE, DELETE                      | Manage brand associations        |
| [Clients](/api-reference/integrations/clients)                | CREATE, UPDATE, DELETE                      | Sync client/account data         |
| [Contracts](/api-reference/integrations/contracts)            | CREATE, UPDATE, DELETE, Attach/Detach Users | Manage contract integrations     |
| [Positions](/api-reference/integrations/positions)            | CREATE, UPDATE, DELETE                      | Manage user positions            |
| [Position Categories](/api-reference/integrations/categories) | CREATE, UPDATE, DELETE                      | Manage position categories       |
| [Projects](/api-reference/integrations/projects)              | CREATE, UPDATE, DELETE                      | Manage project synchronization   |
| [Teams](/api-reference/integrations/teams)                    | CREATE, UPDATE, Attach/Detach Users         | Sync team data within workspaces |
| [Users](/api-reference/integrations/users)                    | CREATE, UPDATE, DELETE, Assign Position     | Manage user provisioning         |
| [User Leaves](/api-reference/integrations/user-leaves)        | CREATE                                      | Manage leave types               |
| [Workspaces](/api-reference/integrations/workspaces)          | CREATE, UPDATE                              | Sync workspace/team data         |
| [Working Time](/api-reference/integrations/working-time)      | CREATE, DELETE                              | Sync time tracking data          |

## External ID Mapping

The core feature of the Integrations API is external ID mapping. When you create an entity through the integration endpoints:

1. **You provide** the external ID (from your system)
2. **COR creates** the entity and stores the mapping
3. **Future operations** can reference either the external ID or the COR ID

This allows you to:

* Update or delete entities using their external IDs
* Query integration status to determine if an entity is already synced
* Route webhook events to the correct external endpoint

### Example Flow

```mermaid theme={null}
sequenceDiagram
    participant Salesforce
    participant IntegrationsAPI as Integrations API
    participant CORAPI as COR API
    participant IntDB as Integrations DB
    participant MainDB as Main DB

    Salesforce->>IntegrationsAPI: POST /v2/integrations/projects
    Note right of Salesforce: external_id: "SF-OPP-123"
    
    IntegrationsAPI->>CORAPI: Create project
    CORAPI->>MainDB: Insert project
    MainDB-->>CORAPI: project_id: 45678
    CORAPI-->>IntegrationsAPI: Project created
    
    IntegrationsAPI->>IntDB: Store mapping
    Note right of IntDB: SF-OPP-123 → 45678
    
    IntegrationsAPI-->>Salesforce: 201 Created
    Note left of IntegrationsAPI: cor_id: 45678
```

## Response Codes

All integration endpoints use standard HTTP status codes:

| Code                        | Description                             |
| --------------------------- | --------------------------------------- |
| `200 OK`                    | Operation successful                    |
| `201 Created`               | Resource created successfully           |
| `400 Bad Request`           | Invalid data or missing required fields |
| `401 Unauthorized`          | Invalid or expired token                |
| `403 Forbidden`             | Insufficient permissions                |
| `404 Not Found`             | Resource not found                      |
| `422 Unprocessable Entity`  | Validation error                        |
| `500 Internal Server Error` | Server error                            |

## Error Codes

The API returns specific error codes for better error handling:

| Code    | Description                |
| ------- | -------------------------- |
| `ZC001` | Generic Error              |
| `ZC002` | Validation Error           |
| `ZC003` | API Request Exception      |
| `ZC004` | Query Exception            |
| `ZC005` | External Request Exception |

## Quick Start

### 1. Create an integrated project

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://integrations.projectcor.com/v2/integrations/projects' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "metadata": {
      "source": "SALESFORCE"
    },
    "id": "SF-OPP-12345",
    "name": "Website Redesign Project",
    "client_id": "SF-ACC-67890",
    "start": "2025-01-15",
    "end": "2025-03-31"
  }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://integrations.projectcor.com/v2/integrations/projects',
      headers={
          'Authorization': f'Bearer {access_token}',
          'Content-Type': 'application/json'
      },
      json={
          'metadata': {
              'source': 'SALESFORCE'
          },
          'id': 'SF-OPP-12345',
          'name': 'Website Redesign Project',
          'client_id': 'SF-ACC-67890',
          'start': '2025-01-15',
          'end': '2025-03-31'
      }
  )

  project = response.json()
  print(f"Created project with COR ID: {project['id']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://integrations.projectcor.com/v2/integrations/projects',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        metadata: {
          source: 'SALESFORCE'
        },
        id: 'SF-OPP-12345',
        name: 'Website Redesign Project',
        client_id: 'SF-ACC-67890',
        start: '2025-01-15',
        end: '2025-03-31'
      })
    }
  );

  const project = await response.json();
  console.log(`Created project with COR ID: ${project.id}`);
  ```
</CodeGroup>

### 2. Update using external ID

```bash theme={null}
curl --location --request PUT 'https://integrations.projectcor.com/v2/integrations/projects/SF-OPP-12345' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "metadata": {
    "source": "SALESFORCE"
  },
  "name": "Website Redesign Project - Phase 2"
}'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Projects" icon="folder" href="/api-reference/integrations/projects">
    Integrate project data between COR and external systems
  </Card>

  <Card title="Clients" icon="building" href="/api-reference/integrations/clients">
    Sync client and account information
  </Card>

  <Card title="Users" icon="users" href="/api-reference/integrations/users">
    Manage user provisioning and assignments
  </Card>

  <Card title="Contracts" icon="file-contract" href="/api-reference/integrations/contracts">
    Handle contract integrations with user associations
  </Card>
</CardGroup>

<Note>
  **Need help?** Contact our support team at [help@projectcor.com](mailto:help@projectcor.com) or visit [COR Support](https://cor.zendesk.com/).
</Note>