API and connexion
      Back to home
      1. Centre d'aide
      2. Lead Management
      3. API and connexion

      Full User Integration with Oplead API: Webhooks, Batch Sync, and Assignment Rules

      Learn how to automatically import and update users in the Oplead platform using webhooks, scheduled polling, and how to configure attribution rules via the REST API.

      This guide is for developers implementing user integration with Oplead. It covers every supported integration scenario — real-time sync, batch updates, and rule-based assignment.

      🔐 Prerequisites

      Before getting started:

      • A valid API token (ask your platform admin)

      • An API testing tool (Postman, curl, etc.)

      • Familiarity with Oplead API schema (Schema tab in Swagger)

      • Required user fields:

        • civility, lastname, login, and valid email

        • Full address with country, zip code, and city

        • A valid profile (GET /v1/settings/user-profiles)

        • A valid parentUserIdentifier (respecting profile hierarchy)

      CASE 1 — Webhook Integration (Real-Time)

      Flow

      1. The source system sends a webhook on user create/update.

      2. Middleware intercepts and triggers:

        • POST /v1/users if the user doesn't exist

        • PUT /v1/users/{userIdentification} if the user already exists

      3. API response confirms success or returns an error

      api

      Use ?test=true during development to avoid changing production data.

      CASE 2 — Batch Integration (Scheduled Polling)

      Polling Flow

      1. A scheduled task queries the source system’s API

      2. Retrieves new/updated users

      3. Makes the appropriate API call:

        • POST /v1/users (create)

        • PUT /v1/users/{userIdentification} (update)

      4. Validates the API response

      api cas 2

      ⚠️ Avoid syncing users more than once per day unless you throttle your API usage.

      User Identification Strategy

      If you can’t store the user ID returned after POST, use a unique accountNumber:

      • Try PUT with accountNumber

      • If the API returns 404, then proceed with POST

      Lead Assignment Rules via API

      These rules only apply if enabled for your Oplead platform.

      1. Geographical Criteria

      Defines which countries, counties, or zip codes a user covers.

      Endpoints:

      • GET /v1/types/countries

      • GET /v1/types/country/{code}

      • PUT /v1/users/{id}/rule/geographical

      {
        "handledCountries": [
          {
            "handledCountry": { "code": "FR" },
            "handledCounties": [
              {
                "handledCounty": { "number": "75" },
                "handledPostCodeZips": ["75001", "75002"]
              }
            ]
          }
        ]
      }

      2. Radius Criteria (maxDistance)

      Maximum distance in kilometers from the user to the lead.

      // PUT /v1/users/{id}/rule/max-distance
      { "maxDistance": 30 }

      3. Competences (Ranges and Request Types)

      • Only Range enabled:

      [
        { "range": { "code": "RNG_XXX" } },
        { "range": { "code": "RNG_YYY" } }
      ]

      • Both Range and Request Type enabled:

      [
        { "range": { "code": "RNG_XXX" }, "requestType": { "code": "RTY_XXX" } },
        { "range": { "code": "RNG_YYY" }, "requestType": { "code": "RTY_YYY" } }
      ]

      4. Contact Profiles

      Assign contact profile codes to users.

      [
        { "code": "CPR_XXX" },
        { "code": "CPR_YYY" }
      ]

      5. Contact Profile Types

      Two possible values: "pro" (professional) and "single" (individual).

      // PUT /v1/users/{id}/rule/profile-types
      ["pro", "single"]

      Best Practices for a Reliable Integration

      • Protect your API token: Never expose it in client-side code or public URLs.

      • Use codes over labels: Codes (e.g., FR, RNG_XXX) are stable and not language-dependent.

      • Leverage test=true: Avoid data persistence during tests — all logic runs without real impact.

      • Store Oplead user IDs: Distinguish between create/update operations more easily.

      • Use accountNumber if ID isn’t stored: It must be unique per user and enables reliable lookups.

      • Throttle batch updates: Don't sync more than once a day unless strictly controlled.

      • Escalate 500 errors through your admin: If errors are unclear, contact Oplead Care via your platform admin.

      Why industrialize user integration with Oplead?

      • Automation: No manual user entry — everything flows automatically via APIs.

      • Real-time sync with Webhooks: Instant updates from your source system to Oplead.

      • Scalability: Easily handle high volumes of user data across organizations or regions.

      • Smart assignment logic: Lead distribution is handled dynamically based on user criteria.

      • Secure by design: Token-based authentication, test mode (test=true), and clean separation of environments.

      • Flexible integration models: Choose real-time, batch, or hybrid depending on your infrastructure.