POST /bulk/jobs API

Submit a new asynchronous geocoding job.

Accepts a large batch of addresses or queries, downloads the payload if necessary, and schedules processing. Results are delivered via webhook and can also be polled through the REST API.

Parameters

Name	In	Type	Required	Description
`X-Idempotency-Key`	header	string	No	Guards against duplicate submissions. When supplied, repeated POST requests with the same value within 24 hours will return the first response.

X-Idempotency-KeyheaderOptional
Typestring
Guards against duplicate submissions. When supplied, repeated POST requests with the same value within 24 hours will return the first response.

Request body

application/json → BulkJobCreateRequest

application/json

{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv",
    "encoding": "utf-8"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "whsec_1234567890abcdef",
    "retry_policy": {
      "max_attempts": 5,
      "initial_delay_seconds": 30,
      "strategy": "exponential"
    }
  },
  "options": {
    "output_format": "geojson",
    "truncate_at": 5,
    "priority": "high"
  },
  "metadata": {
    "requested_by": "ops@example.com",
    "batch_id": "sprint-42"
  }
}

Download CSV payload from HTTPS with webhook delivery.

{
  "input": {
    "transport": "s3",
    "url": "s3://geobridge-inputs/batches/2024/05/15/addresses.ndjson.gz",
    "compression": "gzip",
    "content_type": "application/x-ndjson"
  },
  "callback": {
    "url": "https://api.customer.example/webhooks/geobridge",
    "secret": "whsec_f2e9041b847d40b5",
    "signature_header": "X-Custom-Signature",
    "retry_policy": {
      "max_attempts": 4,
      "initial_delay_seconds": 60,
      "strategy": "exponential"
    }
  },
  "options": {
    "output_format": "ndjson",
    "keep_intermediate_files": true
  },
  "metadata": {
    "project": "quarterly-refresh",
    "requested_by": "data.platform@example.com"
  }
}

Process gzip-compressed NDJSON stored in Amazon S3.

{
  "input": {
    "transport": "inline",
    "records": [
      {
        "id": "store-001",
        "text": "123 Main St New York NY",
        "sources": [
          "openaddresses"
        ],
        "layers": [
          "address"
        ]
      },
      {
        "id": "store-002",
        "structured": {
          "address": "1600 Amphitheatre Parkway",
          "locality": "Mountain View",
          "region": "CA",
          "country": "US"
        }
      },
      {
        "id": "store-003",
        "structured": {
          "locality": "Seattle",
          "region": "WA",
          "country": "US"
        },
        "layers": [
          "locality"
        ]
      }
    ],
    "encoding": "utf-8"
  },
  "callback": {
    "url": "https://crm.example.com/webhooks/geocoding",
    "secret": "whsec_71c0dc9cf4ab4b8c"
  },
  "options": {
    "output_format": "csv",
    "truncate_at": 3
  },
  "metadata": {
    "campaign": "spring-popups",
    "requested_by": "marketing@example.com"
  }
}

Submit a small batch inline with mixed query types.

Sample responses

202 Success — Job accepted for processing.
application/json → BulkJobResponse
Newly queued bulk job.
{ "id": "123e4567-e89b-12d3-a456-426614174000", "status": "queued", "submitted_at": "2024-03-18T12:40:00Z", "input": { "transport": "https", "url": "https://files.example.com/batches/sprint-42.csv", "compression": "gzip", "content_type": "text/csv" }, "callback": { "url": "https://app.example.com/webhooks/geocoding", "secret": "whsec_example_secret_01", "signature_header": "X-Geobridge-Signature", "retry_policy": { "max_attempts": 5, "initial_delay_seconds": 30, "strategy": "exponential" } }, "options": { "output_format": "geojson", "truncate_at": 5 }, "metadata": { "requested_by": "ops@example.com", "batch_id": "sprint-42" }, "statistics": { "total_records": 0, "processed_records": 0, "successful_records": 0, "failed_records": 0 }, "delivery_attempts": [] }

400 Client error — Invalid payload supplied.

application/problem+json → Problem

Validation errors for the submitted job.

{
  "type": "https://docs.geobridge.io/problems/invalid-body",
  "title": "Invalid request body",
  "status": 400,
  "detail": "input.url must point to an HTTPS resource.",
  "errors": [
    {
      "field": "input.url",
      "message": "Only HTTPS URLs are supported for transport=https."
    },
    {
      "field": "callback.secret",
      "message": "Must be at least 16 characters long."
    }
  ]
}

401 Client error — Missing or invalid API key.

application/problem+json → Problem

API key header omitted.

{
  "type": "https://docs.geobridge.io/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key is missing or invalid."
}

409 Client error — Duplicate job submission detected via idempotency key.

application/problem+json → Problem

Idempotent submission already processed.

{
  "type": "https://docs.geobridge.io/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Job already exists for idempotency key bulk-sprint-42."
}

422 Client error — Semantically invalid job payload.

application/problem+json → Problem

Payload conflicts with business rules.

{
  "type": "https://docs.geobridge.io/problems/unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "options.truncate_at cannot exceed 10 for geojson output.",
  "errors": [
    {
      "field": "options.truncate_at",
      "message": "Must be between 1 and 10 when output_format=geojson."
    }
  ]
}

429 Client error — Too many requests. Retry after the rate limit resets.

application/problem+json → Problem

Caller exceeded job submission rate.

{
  "type": "https://docs.geobridge.io/problems/too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit of 5 job submissions per minute exceeded."
}

500 Server error — Unexpected server error.

application/problem+json → Problem

Internal error while enqueuing job.

{
  "type": "https://docs.geobridge.io/problems/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Unexpected exception while writing job metadata."
}

Code samples

202 Accepted

# 202 Accepted — Creates a bulk job with HTTPS input and webhook callback.
curl -s -X POST 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: bulk-sprint-42' \
  -d ' \
{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET",
    "retry_policy": {
      "max_attempts": 5,
      "initial_delay_seconds": 30,
      "strategy": "exponential"
    }
  },
  "options": {
    "output_format": "geojson",
    "truncate_at": 5
  },
  "metadata": {
    "requested_by": "ops@example.com",
    "batch_id": "sprint-42"
  }
} \
'

// 202 Accepted — Creates a bulk job with HTTPS input and webhook callback.
// Node.js 18+ with global fetch support.
const requestUrl = 'https://api-na.geobridge.io/v1/bulk/jobs';
const response = await fetch(requestUrl, {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': 'bulk-sprint-42'
  },
  body: JSON.stringify({
      "input": {
        "transport": "https",
        "url": "https://files.example.com/batches/sprint-42.csv",
        "compression": "gzip",
        "content_type": "text/csv"
      },
      "callback": {
        "url": "https://app.example.com/webhooks/geocoding",
        "secret": "YOUR_WEBHOOK_SECRET",
        "retry_policy": {
          "max_attempts": 5,
          "initial_delay_seconds": 30,
          "strategy": "exponential"
        }
      },
      "options": {
        "output_format": "geojson",
        "truncate_at": 5
      },
      "metadata": {
        "requested_by": "ops@example.com",
        "batch_id": "sprint-42"
      }
    }),
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

# 202 Accepted — Creates a bulk job with HTTPS input and webhook callback.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = None
headers = {
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json",
  "X-Idempotency-Key": "bulk-sprint-42"
}
payload = {
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET",
    "retry_policy": {
      "max_attempts": 5,
      "initial_delay_seconds": 30,
      "strategy": "exponential"
    }
  },
  "options": {
    "output_format": "geojson",
    "truncate_at": 5
  },
  "metadata": {
    "requested_by": "ops@example.com",
    "batch_id": "sprint-42"
  }
}
response = requests.post(url, params=params, headers=headers, json=payload, timeout=20)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

// 202 Accepted — Creates a bulk job with HTTPS input and webhook callback.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "strings"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  req, err := http.NewRequest(http.MethodPost, u.String(), strings.NewReader(`{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET",
    "retry_policy": {
      "max_attempts": 5,
      "initial_delay_seconds": 30,
      "strategy": "exponential"
    }
  },
  "options": {
    "output_format": "geojson",
    "truncate_at": 5
  },
  "metadata": {
    "requested_by": "ops@example.com",
    "batch_id": "sprint-42"
  }
}`))
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-Idempotency-Key", "bulk-sprint-42")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

// 202 Accepted — Creates a bulk job with HTTPS input and webhook callback.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .header("Content-Type", "application/json")
        .header("X-Idempotency-Key", "bulk-sprint-42")
        .method("POST", HttpRequest.BodyPublishers.ofString("{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\",
    \\\"compression\\\": \\\"gzip\\\",
    \\\"content_type\\\": \\\"text/csv\\\"
  },
  \\\"callback\\\": {
    \\\"url\\\": \\\"https://app.example.com/webhooks/geocoding\\\",
    \\\"secret\\\": \\\"YOUR_WEBHOOK_SECRET\\\",
    \\\"retry_policy\\\": {
      \\\"max_attempts\\\": 5,
      \\\"initial_delay_seconds\\\": 30,
      \\\"strategy\\\": \\\"exponential\\\"
    }
  },
  \\\"options\\\": {
    \\\"output_format\\\": \\\"geojson\\\",
    \\\"truncate_at\\\": 5
  },
  \\\"metadata\\\": {
    \\\"requested_by\\\": \\\"ops@example.com\\\",
    \\\"batch_id\\\": \\\"sprint-42\\\"
  }
}"))
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

// 202 Accepted — Creates a bulk job with HTTPS input and webhook callback.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api-na.geobridge.io/v1/bulk/jobs");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("X-Idempotency-Key", "bulk-sprint-42");
        request.Content = new StringContent(
            "{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\",
    \\\"compression\\\": \\\"gzip\\\",
    \\\"content_type\\\": \\\"text/csv\\\"
  },
  \\\"callback\\\": {
    \\\"url\\\": \\\"https://app.example.com/webhooks/geocoding\\\",
    \\\"secret\\\": \\\"YOUR_WEBHOOK_SECRET\\\",
    \\\"retry_policy\\\": {
      \\\"max_attempts\\\": 5,
      \\\"initial_delay_seconds\\\": 30,
      \\\"strategy\\\": \\\"exponential\\\"
    }
  },
  \\\"options\\\": {
    \\\"output_format\\\": \\\"geojson\\\",
    \\\"truncate_at\\\": 5
  },
  \\\"metadata\\\": {
    \\\"requested_by\\\": \\\"ops@example.com\\\",
    \\\"batch_id\\\": \\\"sprint-42\\\"
  }
}",
            Encoding.UTF8,
            "application/json");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

400 Bad Request

# 400 Bad Request — Missing callback object results in validation error when creating a job.
curl -s -X POST 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d ' \
{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  }
} \
'

// 400 Bad Request — Missing callback object results in validation error when creating a job.
// Node.js 18+ with global fetch support.
const requestUrl = 'https://api-na.geobridge.io/v1/bulk/jobs';
const response = await fetch(requestUrl, {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "input": {
        "transport": "https",
        "url": "https://files.example.com/batches/sprint-42.csv"
      }
    }),
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

# 400 Bad Request — Missing callback object results in validation error when creating a job.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = None
headers = {
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json"
}
payload = {
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  }
}
response = requests.post(url, params=params, headers=headers, json=payload, timeout=20)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

// 400 Bad Request — Missing callback object results in validation error when creating a job.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "strings"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  req, err := http.NewRequest(http.MethodPost, u.String(), strings.NewReader(`{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  }
}`))
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

// 400 Bad Request — Missing callback object results in validation error when creating a job.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .header("Content-Type", "application/json")
        .method("POST", HttpRequest.BodyPublishers.ofString("{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\"
  }
}"))
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

// 400 Bad Request — Missing callback object results in validation error when creating a job.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api-na.geobridge.io/v1/bulk/jobs");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        request.Headers.Add("Content-Type", "application/json");
        request.Content = new StringContent(
            "{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\"
  }
}",
            Encoding.UTF8,
            "application/json");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

401 Unauthorized

# 401 Unauthorized — Omitting the API key header triggers authentication failure.
# Deliberately omits X-API-Key header to demonstrate 401 Unauthorized.
curl -s -X POST 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d ' \
{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
} \
'

// 401 Unauthorized — Omitting the API key header triggers authentication failure.
// Missing X-API-Key header is intentional to trigger 401.
// Node.js 18+ with global fetch support.
const requestUrl = 'https://api-na.geobridge.io/v1/bulk/jobs';
const response = await fetch(requestUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "input": {
        "transport": "https",
        "url": "https://files.example.com/batches/sprint-42.csv"
      },
      "callback": {
        "url": "https://app.example.com/webhooks/geocoding",
        "secret": "YOUR_WEBHOOK_SECRET"
      }
    }),
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

# 401 Unauthorized — Omitting the API key header triggers authentication failure.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = None
headers = {
  "Content-Type": "application/json"
}
payload = {
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}
response = requests.post(url, params=params, headers=headers, json=payload, timeout=20)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

// 401 Unauthorized — Omitting the API key header triggers authentication failure.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "strings"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  req, err := http.NewRequest(http.MethodPost, u.String(), strings.NewReader(`{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}`))
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("Content-Type", "application/json")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

// 401 Unauthorized — Omitting the API key header triggers authentication failure.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .method("POST", HttpRequest.BodyPublishers.ofString("{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\"
  },
  \\\"callback\\\": {
    \\\"url\\\": \\\"https://app.example.com/webhooks/geocoding\\\",
    \\\"secret\\\": \\\"YOUR_WEBHOOK_SECRET\\\"
  }
}"))
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

// 401 Unauthorized — Omitting the API key header triggers authentication failure.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api-na.geobridge.io/v1/bulk/jobs");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("Content-Type", "application/json");
        request.Content = new StringContent(
            "{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\"
  },
  \\\"callback\\\": {
    \\\"url\\\": \\\"https://app.example.com/webhooks/geocoding\\\",
    \\\"secret\\\": \\\"YOUR_WEBHOOK_SECRET\\\"
  }
}",
            Encoding.UTF8,
            "application/json");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

422 Unprocessable Entity

# 422 Unprocessable Entity — Callback object is present but missing the required url, triggering semantic validation.
curl -s -X POST 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: bulk-sprint-42' \
  -d ' \
{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "secret": "YOUR_WEBHOOK_SECRET"
  }
} \
'

// 422 Unprocessable Entity — Callback object is present but missing the required url, triggering semantic validation.
// Node.js 18+ with global fetch support.
const requestUrl = 'https://api-na.geobridge.io/v1/bulk/jobs';
const response = await fetch(requestUrl, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': 'bulk-sprint-42'
  },
  body: JSON.stringify({
    input: {
      transport: 'https',
      url: 'https://files.example.com/batches/sprint-42.csv',
      compression: 'gzip',
      content_type: 'text/csv'
    },
    callback: {
      secret: 'YOUR_WEBHOOK_SECRET'
    }
  }),
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

# 422 Unprocessable Entity — Callback object is present but missing the required url, triggering semantic validation.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = None
headers = {
  "Accept": "application/json",
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json",
  "X-Idempotency-Key": "bulk-sprint-42"
}
payload = {
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}
response = requests.post(url, params=params, headers=headers, json=payload, timeout=20)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

// 422 Unprocessable Entity — Callback object is present but missing the required url, triggering semantic validation.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "strings"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  body := strings.NewReader(`{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}`)
  req, err := http.NewRequest(http.MethodPost, u.String(), body)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-Idempotency-Key", "bulk-sprint-42")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

// 422 Unprocessable Entity — Callback object is present but missing the required url, triggering semantic validation.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    String body = """
{
  \"input\": {
    \"transport\": \"https\",
    \"url\": \"https://files.example.com/batches/sprint-42.csv\",
    \"compression\": \"gzip\",
    \"content_type\": \"text/csv\"
  },
  \"callback\": {
    \"secret\": \"YOUR_WEBHOOK_SECRET\"
  }
}
""";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .header("Content-Type", "application/json")
        .header("X-Idempotency-Key", "bulk-sprint-42")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

// 422 Unprocessable Entity — Callback object is present but missing the required url, triggering semantic validation.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(HttpMethod.Post, "https://api-na.geobridge.io/v1/bulk/jobs");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        request.Headers.Add("X-Idempotency-Key", "bulk-sprint-42");
        request.Content = new StringContent(
            """
{
  \"input\": {
    \"transport\": \"https\",
    \"url\": \"https://files.example.com/batches/sprint-42.csv\",
    \"compression\": \"gzip\",
    \"content_type\": \"text/csv\"
  },
  \"callback\": {
    \"secret\": \"YOUR_WEBHOOK_SECRET\"
  }
}
""",
            Encoding.UTF8,
            "application/json");

        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

429 Too Many Requests

# 429 Too Many Requests — Rapidly resubmitting bulk jobs exceeds the rate limit; wait before retrying.
curl -s -X POST 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: bulk-sprint-42' \
  -d ' \
{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
} \
'

// 429 Too Many Requests — Rapidly resubmitting bulk jobs exceeds the rate limit; wait before retrying.
// Node.js 18+ with global fetch support.
const requestUrl = 'https://api-na.geobridge.io/v1/bulk/jobs';
const response = await fetch(requestUrl, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': 'bulk-sprint-42'
  },
  body: JSON.stringify({
    input: {
      transport: 'https',
      url: 'https://files.example.com/batches/sprint-42.csv',
      compression: 'gzip',
      content_type: 'text/csv'
    },
    callback: {
      url: 'https://app.example.com/webhooks/geocoding',
      secret: 'YOUR_WEBHOOK_SECRET'
    }
  }),
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

# 429 Too Many Requests — Rapidly resubmitting bulk jobs exceeds the rate limit; wait before retrying.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = None
headers = {
  "Accept": "application/json",
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json",
  "X-Idempotency-Key": "bulk-sprint-42"
}
payload = {
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}
response = requests.post(url, params=params, headers=headers, json=payload, timeout=20)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

// 429 Too Many Requests — Rapidly resubmitting bulk jobs exceeds the rate limit; wait before retrying.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "strings"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  body := strings.NewReader(`{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv",
    "compression": "gzip",
    "content_type": "text/csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}`)
  req, err := http.NewRequest(http.MethodPost, u.String(), body)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-Idempotency-Key", "bulk-sprint-42")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

// 429 Too Many Requests — Rapidly resubmitting bulk jobs exceeds the rate limit; wait before retrying.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    String body = """
{
  \"input\": {
    \"transport\": \"https\",
    \"url\": \"https://files.example.com/batches/sprint-42.csv\",
    \"compression\": \"gzip\",
    \"content_type\": \"text/csv\"
  },
  \"callback\": {
    \"url\": \"https://app.example.com/webhooks/geocoding\",
    \"secret\": \"YOUR_WEBHOOK_SECRET\"
  }
}
""";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .header("Content-Type", "application/json")
        .header("X-Idempotency-Key", "bulk-sprint-42")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

// 429 Too Many Requests — Rapidly resubmitting bulk jobs exceeds the rate limit; wait before retrying.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(HttpMethod.Post, "https://api-na.geobridge.io/v1/bulk/jobs");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        request.Headers.Add("X-Idempotency-Key", "bulk-sprint-42");
        request.Content = new StringContent(
            """
{
  \"input\": {
    \"transport\": \"https\",
    \"url\": \"https://files.example.com/batches/sprint-42.csv\",
    \"compression\": \"gzip\",
    \"content_type\": \"text/csv\"
  },
  \"callback\": {
    \"url\": \"https://app.example.com/webhooks/geocoding\",
    \"secret\": \"YOUR_WEBHOOK_SECRET\"
  }
}
""",
            Encoding.UTF8,
            "application/json");

        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

409 Conflict

# 409 Conflict — Reusing an idempotency key returns the original response instead of creating a new job.
curl -s -X POST 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: bulk-sprint-42' \
  -d ' \
{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
} \
'

// 409 Conflict — Reusing an idempotency key returns the original response instead of creating a new job.
// Node.js 18+ with global fetch support.
const requestUrl = 'https://api-na.geobridge.io/v1/bulk/jobs';
const response = await fetch(requestUrl, {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': 'bulk-sprint-42'
  },
  body: JSON.stringify({
      "input": {
        "transport": "https",
        "url": "https://files.example.com/batches/sprint-42.csv"
      },
      "callback": {
        "url": "https://app.example.com/webhooks/geocoding",
        "secret": "YOUR_WEBHOOK_SECRET"
      }
    }),
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

# 409 Conflict — Reusing an idempotency key returns the original response instead of creating a new job.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = None
headers = {
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json",
  "X-Idempotency-Key": "bulk-sprint-42"
}
payload = {
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}
response = requests.post(url, params=params, headers=headers, json=payload, timeout=20)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

// 409 Conflict — Reusing an idempotency key returns the original response instead of creating a new job.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "strings"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  req, err := http.NewRequest(http.MethodPost, u.String(), strings.NewReader(`{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}`))
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-Idempotency-Key", "bulk-sprint-42")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

// 409 Conflict — Reusing an idempotency key returns the original response instead of creating a new job.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .header("Content-Type", "application/json")
        .header("X-Idempotency-Key", "bulk-sprint-42")
        .method("POST", HttpRequest.BodyPublishers.ofString("{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\"
  },
  \\\"callback\\\": {
    \\\"url\\\": \\\"https://app.example.com/webhooks/geocoding\\\",
    \\\"secret\\\": \\\"YOUR_WEBHOOK_SECRET\\\"
  }
}"))
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

// 409 Conflict — Reusing an idempotency key returns the original response instead of creating a new job.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api-na.geobridge.io/v1/bulk/jobs");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("X-Idempotency-Key", "bulk-sprint-42");
        request.Content = new StringContent(
            "{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\"
  },
  \\\"callback\\\": {
    \\\"url\\\": \\\"https://app.example.com/webhooks/geocoding\\\",
    \\\"secret\\\": \\\"YOUR_WEBHOOK_SECRET\\\"
  }
}",
            Encoding.UTF8,
            "application/json");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

500 Internal Server Error

# 500 Internal Server Error — Illustrates retry logic when the bulk submission endpoint fails unexpectedly.
curl -s -X POST 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: bulk-sprint-42' \
  -d ' \
{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
} \
'

// 500 Internal Server Error — Illustrates retry logic when the bulk submission endpoint fails unexpectedly.
// Node.js 18+ with global fetch support.
const requestUrl = 'https://api-na.geobridge.io/v1/bulk/jobs';
const response = await fetch(requestUrl, {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': 'bulk-sprint-42'
  },
  body: JSON.stringify({
      "input": {
        "transport": "https",
        "url": "https://files.example.com/batches/sprint-42.csv"
      },
      "callback": {
        "url": "https://app.example.com/webhooks/geocoding",
        "secret": "YOUR_WEBHOOK_SECRET"
      }
    }),
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

# 500 Internal Server Error — Illustrates retry logic when the bulk submission endpoint fails unexpectedly.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = None
headers = {
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json",
  "X-Idempotency-Key": "bulk-sprint-42"
}
payload = {
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}
response = requests.post(url, params=params, headers=headers, json=payload, timeout=20)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

// 500 Internal Server Error — Illustrates retry logic when the bulk submission endpoint fails unexpectedly.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "strings"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  req, err := http.NewRequest(http.MethodPost, u.String(), strings.NewReader(`{
  "input": {
    "transport": "https",
    "url": "https://files.example.com/batches/sprint-42.csv"
  },
  "callback": {
    "url": "https://app.example.com/webhooks/geocoding",
    "secret": "YOUR_WEBHOOK_SECRET"
  }
}`))
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-Idempotency-Key", "bulk-sprint-42")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

// 500 Internal Server Error — Illustrates retry logic when the bulk submission endpoint fails unexpectedly.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .header("Content-Type", "application/json")
        .header("X-Idempotency-Key", "bulk-sprint-42")
        .method("POST", HttpRequest.BodyPublishers.ofString("{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\"
  },
  \\\"callback\\\": {
    \\\"url\\\": \\\"https://app.example.com/webhooks/geocoding\\\",
    \\\"secret\\\": \\\"YOUR_WEBHOOK_SECRET\\\"
  }
}"))
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

// 500 Internal Server Error — Illustrates retry logic when the bulk submission endpoint fails unexpectedly.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api-na.geobridge.io/v1/bulk/jobs");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("X-Idempotency-Key", "bulk-sprint-42");
        request.Content = new StringContent(
            "{
  \\\"input\\\": {
    \\\"transport\\\": \\\"https\\\",
    \\\"url\\\": \\\"https://files.example.com/batches/sprint-42.csv\\\"
  },
  \\\"callback\\\": {
    \\\"url\\\": \\\"https://app.example.com/webhooks/geocoding\\\",
    \\\"secret\\\": \\\"YOUR_WEBHOOK_SECRET\\\"
  }
}",
            Encoding.UTF8,
            "application/json");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Try it live

Save your API key once and reuse it across endpoints. Configure the request below and send it directly from the docs.

API key

Stored locally in your browser. Removing it clears access for this device.

Server

Header parameters

X-Idempotency-Key

Guards against duplicate submissions. When supplied, repeated POST requests with the same value within 24 hours will return the first response.

Request body

Content type: application/json

application/jsonRequired • Schema: object

Input mode: Form Raw JSON

Form limitations:

input:Polymorphic schemas (oneOf/anyOf/not) are not yet supported in form mode.
metadata:Dynamic key objects (additionalProperties) are not supported. Use raw JSON mode.

Switch to Raw JSON mode to edit unsupported fields.

input: Polymorphic schemas (oneOf/anyOf/not) are not yet supported in form mode.

callback*

url*

HTTPS endpoint that will receive job completion notifications.

secret*

Shared secret used to compute webhook signatures.

signature header

Name of the header that transports the HMAC signature.

replay window seconds

Time window in seconds in which the receiver must reject duplicate deliveries.

retry policy

max attempts

initial delay seconds

strategy

options

output format

truncate at

Optional limit on the number of matches returned per record.

keep intermediate files

priority

metadata: Dynamic key objects (additionalProperties) are not supported. Use raw JSON mode.

*** End of File

Configure the request and select “Send request” to preview the response.

—

Response headers

POST /bulk/jobs API

Parameters

Request body

application/json

Sample responses

application/json → BulkJobResponse

application/problem+json → Problem

application/problem+json → Problem

application/problem+json → Problem

application/problem+json → Problem

application/problem+json → Problem

application/problem+json → Problem

Code samples

202 Accepted

400 Bad Request

401 Unauthorized

422 Unprocessable Entity

429 Too Many Requests

409 Conflict

500 Internal Server Error

Try it live