API Technical Overview

Devensoft Web API Overview

• Version: v1.0
• Authentication: OAuth 2.0 (Client Credentials) using Bearer tokens
• Content Types: JSON (primary), CSV (optional for some endpoints)
• Purpose: RESTful endpoints for managing business entities like Targets, Contacts, and supporting collections.

Key Features

• Target Management: Create, update, delete, and retrieve Targets.
• Program Management: Retrieve Programs and Activity Map items
• Configuration: Fetch metadata for target fields (supports filtering and CSV export).
• Collections: Retrieve reference data (countries, deal phases, picklists).
• Contacts: Search and paginate contacts with optional filters.
• Authentication: Obtain access tokens via /token endpoint.

Authentication

• Endpoint: POST /token
• Flow: OAuth 2.0 Client Credentials
• Required Parameters: grant_type=client_credentials, client_id, client_secret
• Response: access_token, token_type, expires_in (3600 seconds)

Main Endpoints

Collections

• GET /v1/collections/countries → List all countries.
• GET /v1/collections/deal-phases → List all deal phases (deal stages).
• GET /v1/collections/picklists/{category}/{subcategory} → Retrieve picklist items by category/subcategory.

Configuration

• GET /v1/configuration/targets/fields → Retrieve target field metadata.
  • Supports filters: format=json|csv, properties, custom=true|false.

Contacts

• GET /v1/contacts → Retrieve contacts with search, pagination, and deal lead filters.

Targets

• GET /v1/targets → Retrieve targets with extensive filtering (status, phase, deal type, priority, etc.).
• POST /v1/targets → Create a new target.
• PUT /v1/targets/{id} → Update an existing target.
• DELETE /v1/targets/{id} → Soft delete a target.

Programs

• READ

Activity Map

• READ all Hierarchy Levels

Response Patterns

• Success: 200 (GET), 201 (POST)
• Errors:
  • 400 → Bad Request (invalid parameters)
  • 401 → Unauthorized (missing/invalid token)
  • 404 → Not Found (e.g., no custom fields or target not found)
  • 500 → Internal Server Error

Security

• Bearer Token in Header:

  Authorization: Bearer {access_token}
  

Data Models

• CreateTargetCommand → For creating targets.
• TargetUpdateModel → For updating targets.
• TokenResponse → For authentication response.