--- updatedAt: 2026-07-31T17:22:44.000Z agentTools: projectIndex: https://developer.demandbase.com/llms.txt --- # Match companies and contact This endpoint matches companies and contacts against Demandbase's database based on provided firmographic and contact details. This endpoint supports batch matching by accepting an array of match requests. Each object in the requests array must include a unique id and a useful combination of attributes for matching. At a minimum, at least one of the following company identifiers is required: - `name` - `websites` - `email` - `executiveLinkedInHandle` # OpenAPI definition ````json { "openapi": "3.0.1", "info": { "version": "1.0", "title": "B2B API", "description": "The B2B API provides access to endpoints for searching, retrieving, and matching company and contact data.\n\nIt includes support for:\n- **Company records:** Firmographic details, news, technologies, and more.\n- **Contact records:** Current role, employment history, and professional details.\n- **Demandbase Person profiles:** Persistent identities tied to individuals across multiple roles or companies.\n- **Subscriptions:** Monitoring updates to companies and DB Person records.\n## Authentication\nAll requests to the B2B API must be authenticated using a valid API token. If authentication fails, the API will respond with a `401 Unauthorized` status code.\n### Obtaining an API Token\nFor instructions on generating API tokens, see the [Generate and Manage API Key Set](https://support.demandbase.com/hc/en-us/articles/38999526296603-Generate-and-Manage-API-Key-Set) article at the Demandbase Help Center.\n### Authorization Header\nInclude your API token in the `Authorization` header of each request using the Bearer token scheme. Also set the `Content-Type` header to `application/json` when sending JSON payloads.\n#### Example\n```\nAuthorization: Bearer YOUR_API_KEY_HERE\nContent-Type: application/json\n```\n\n> **Note:** Tokens should be treated as sensitive credentials. Do not expose them in public code repositories or client-side applications.", "contact": { "name": "Support", "url": "https://www.demandbase.com/", "email": "support@demandbase.com" } }, "servers": [ { "url": "https://uapi.demandbase.com/data/b2b/v1", "description": "Server URL in Production environment" } ], "paths": { "/match": { "post": { "tags": [ "Sync API" ], "summary": "Match companies and contact", "description": "This endpoint matches companies and contacts against Demandbase's database based on provided firmographic and contact details. This endpoint supports batch matching by accepting an array of match requests.\n\nEach object in the requests array must include a unique id and a useful combination of attributes for matching.\n\nAt a minimum, at least one of the following company identifiers is required:\n- `name`\n- `websites`\n- `email`\n- `executiveLinkedInHandle`", "operationId": "match_1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchRequestDTO" } } } }, "responses": { "200": { "description": "Successful operation or No companies found for query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchResponseDTO" }, "examples": { "SuccessResponse": { "description": "SuccessResponse", "value": { "matches": [ { "id": "id", "companyMatches": [ { "company": { "companyId": 726263, "companyName": "Microsoft Corporation", "address": { "street": "1 Microsoft Way", "city": "Redmond", "state": "WA", "country": "United States" } } } ], "contactMatches": [ { "contact": { "dbPersonDetails": { "dbPersonId": 243908534, "firstName": "Satya", "lastName": "Nadella" }, "employmentDetails": { "contactId": 310227204, "companyId": 726263, "companyName": "Microsoft Corporation", "titles": [ "Chairman and CEO" ], "contactQualityScore": "A+" } } } ] } ] } }, "EmptyCompaniesResponse": { "description": "EmptyCompaniesResponse", "value": { "matches": [ { "id": "2", "companyMatches": [], "contactMatches": [] } ] } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/MatchResponseDTO" }, "examples": { "SuccessResponseXml": { "description": "SuccessResponseXml", "value": { "matches": [ { "id": "1", "companyMatches": [ { "company": { "companyId": 7573216, "companyName": "Google LLC", "address": { "city": "Mountain View", "state": "CA", "country": "United States" } } } ], "contactMatches": [ { "contact": { "dbPersonDetails": { "dbPersonId": 50823422, "firstName": "Stefano", "lastName": "Gessati" }, "employmentDetails": { "contactId": 96208084, "companyId": 7573216, "companyName": "Google LLC", "titles": [ "IT Resident" ] } } } ] }, { "id": "2", "companyMatches": [ { "company": { "companyId": 724468, "companyName": "Apple Inc.", "address": { "city": "Cupertino", "state": "CA", "country": "United States" } } } ], "contactMatches": [ { "contact": { "dbPersonDetails": { "dbPersonId": 215, "firstName": "Tim", "lastName": "Cook" }, "employmentDetails": { "contactId": 317995637, "companyId": 724468, "companyName": "Apple Inc.", "titles": [ "CEO" ], "contactQualityScore": "A+" } } } ] } ] } }, "EmptyCompaniesResponseXml": { "description": "EmptyCompaniesResponseXml", "value": { "matches": [ { "id": "2", "companyMatches": [], "contactMatches": [] } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidRequestsErrorResponse": { "description": "InvalidRequestsErrorResponse", "value": { "errorCode": "400-165", "errorMessage": "The match request should have non empty requests list.", "diagnosticCode": "88c27a04-bd7c-43d6-b133-b0990572e0d2" } }, "InvalidRequestBodyErrorResponse": { "description": "InvalidRequestBodyErrorResponse", "value": { "errorCode": "400-166", "errorMessage": "The request cannot be null.", "diagnosticCode": "58d73e23-2ade-48de-bab1-8bb91f8593eb" } }, "RequiredParamMissingErrorResponse": { "description": "RequiredParamMissingErrorResponse", "value": { "errorCode": "400-164", "errorMessage": "At least one of the following parameters: name, website, email or ticker must be provided for a match.", "diagnosticCode": "8a780506-a4ea-47c0-9837-3ae20d5f8849" } }, "InvalidRequestIdErrorResponse": { "description": "InvalidRequestIdErrorResponse", "value": { "errorCode": "400-167", "errorMessage": "Each request should have a unique ID.", "diagnosticCode": "cca619c0-6f2c-476d-bf9e-916c7e33e90e" } }, "InvalidRequestsSizeErrorResponse": { "description": "InvalidRequestsSizeErrorResponse", "value": { "errorCode": "400-168", "errorMessage": "The match request size should be less than or equal to 30.", "diagnosticCode": "a9f35a64-5d7c-40d9-949d-6b3d440732f4" } }, "InvalidFieldNameErrorResponse": { "description": "InvalidFieldNameErrorResponse", "value": { "errorCode": "400-106", "errorMessage": "{invalidFieldName} Invalid field name.", "diagnosticCode": "3295f2e8-b794-4646-a805-b573e69d43fb" } }, "InvalidMinMatchScoreErrorResponse": { "description": "InvalidMinMatchScoreErrorResponse", "value": { "errorCode": "400-170", "errorMessage": "The minimumMatchScore should be between 0 and 1.", "diagnosticCode": "b823b5fe-0862-4ea5-bb18-cee2d8a69782" } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidRequestsErrorResponseXML": { "description": "InvalidRequestsErrorResponseXML", "value": { "errorCode": "400-165", "errorMessage": "The match request should have non empty requests list.", "diagnosticCode": "88c27a04-bd7c-43d6-b133-b0990572e0d2" } }, "InvalidRequestBodyErrorResponseXML": { "description": "InvalidRequestBodyErrorResponseXML", "value": { "errorCode": "400-166", "errorMessage": "The request cannot be null.", "diagnosticCode": "58d73e23-2ade-48de-bab1-8bb91f8593eb" } }, "RequiredParamMissingErrorResponseXML": { "description": "RequiredParamMissingErrorResponseXML", "value": { "errorCode": "400-164", "errorMessage": "At least one of the following parameters: name, website, email or ticker must be provided for a match.", "diagnosticCode": "8a780506-a4ea-47c0-9837-3ae20d5f8849" } }, "InvalidRequestIdErrorResponseXML": { "description": "InvalidRequestIdErrorResponseXML", "value": { "errorCode": "400-167", "errorMessage": "Each request should have a unique ID.", "diagnosticCode": "cca619c0-6f2c-476d-bf9e-916c7e33e90e" } }, "InvalidRequestsSizeErrorResponseXML": { "description": "InvalidRequestsSizeErrorResponseXML", "value": { "errorCode": "400-168", "errorMessage": "The match request size should be less than or equal to 30.", "diagnosticCode": "a9f35a64-5d7c-40d9-949d-6b3d440732f4" } }, "InvalidFieldNameErrorResponseXML": { "description": "InvalidFieldNameErrorResponseXML", "value": { "errorCode": "400-106", "errorMessage": "{invalidFieldName} Invalid field name.", "diagnosticCode": "3295f2e8-b794-4646-a805-b573e69d43fb" } }, "InvalidMinMatchScoreErrorResponseXML": { "description": "InvalidMinMatchScoreErrorResponseXML", "value": { "errorCode": "400-170", "errorMessage": "The minimumMatchScore should be between 0 and 1.", "diagnosticCode": "b823b5fe-0862-4ea5-bb18-cee2d8a69782" } } } } } }, "401": { "description": "Unauthorized because the user is not authenticated.", "content": { "application/json": { "examples": { "UnauthorizedResponse": { "description": "UnauthorizedResponse", "value": { "status": "Authentication Failed - Unauthorized." } } } } } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://uapi.demandbase.com/data/b2b/v1", "description": "Server URL in Production environment" } ] } } }, "tags": [ { "name": "Sync API", "description": "Synchronous company, contact, matching, news, and logo operations." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "[How To Generate Bearer Tokens](https://developer.demandbase.com/docs/auth-api)", "scheme": "bearer" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "diagnosticCode": { "type": "string" } }, "xml": { "name": "error" } }, "CompanyDTO": { "type": "object", "properties": { "name": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "companyId": { "type": "integer", "format": "int32" } } }, "ContactFetchResponseDTO": { "type": "object", "properties": { "dbPersonDetails": { "$ref": "#/components/schemas/DBPersonDetails" }, "employmentDetails": { "$ref": "#/components/schemas/EmploymentDetails" }, "employmentHistoryList": { "type": "array", "items": { "$ref": "#/components/schemas/Employments" }, "xml": { "wrapped": true } } }, "xml": { "name": "contact" } }, "DBPersonDetails": { "type": "object", "properties": { "dbPersonId": { "type": "integer", "format": "int32" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "type": "integer", "format": "int32" }, "mobileNumber": { "type": "string" }, "educationList": { "type": "array", "items": { "$ref": "#/components/schemas/Education" }, "xml": { "wrapped": true } }, "imageUrl": { "type": "string" }, "socialHandles": { "$ref": "#/components/schemas/SocialHandles" }, "address": { "$ref": "#/components/schemas/AddressDTO" } } }, "Education": { "type": "object", "properties": { "degree": { "type": "string" }, "major": { "type": "string" }, "university": { "type": "string" } } }, "SocialHandles": { "type": "object", "properties": { "twitter": { "type": "string" }, "facebook": { "type": "string" }, "linkedIn": { "type": "string" } } }, "AddressDTO": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "stateCode": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "countryCode": { "type": "string" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "area": { "type": "string" } } }, "CompanyAddressDTO": { "type": "object", "description": "Company address. State and country are returned as codes when available.", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string", "description": "State or province code.", "example": "WA" }, "zip": { "type": "string" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "area": { "type": "string" } } }, "EmploymentDetails": { "type": "object", "properties": { "contactId": { "type": "integer", "format": "int32" }, "companyId": { "type": "integer", "format": "int32" }, "companyName": { "type": "string" }, "contactQualityScore": { "type": "string" }, "description": { "type": "string" }, "startDate": { "type": "string" }, "salary": { "type": "string" }, "salaryCurrency": { "type": "string" }, "active": { "type": "string" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/EmailDetails" }, "xml": { "wrapped": true } }, "lastValidatedDate": { "type": "string" }, "phoneNumbers": { "$ref": "#/components/schemas/PhoneNumbers" }, "jobLevels": { "type": "array", "items": { "$ref": "#/components/schemas/JobLevels" }, "xml": { "wrapped": true } }, "jobFunctions": { "type": "array", "items": { "$ref": "#/components/schemas/JobFunctions" }, "xml": { "wrapped": true } }, "titles": { "type": "array", "items": { "type": "string", "xml": { "name": "title" } }, "xml": { "wrapped": true } } } }, "EmailDetails": { "type": "object", "properties": { "email": { "type": "string" }, "validationStatus": { "type": "string" } } }, "PhoneNumbers": { "type": "object", "properties": { "directNumber": { "type": "string" }, "corporateNumber": { "type": "string" } } }, "JobLevels": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "JobFunctions": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "Employments": { "type": "object", "properties": { "contactId": { "type": "integer", "format": "int32" }, "companyId": { "type": "integer", "format": "int32" }, "companyName": { "type": "string" }, "emails": { "type": "array", "items": { "type": "string", "xml": { "name": "email" } }, "xml": { "wrapped": true } }, "phoneNumbers": { "$ref": "#/components/schemas/PhoneNumbers" }, "active": { "type": "string" }, "jobLevels": { "type": "array", "items": { "$ref": "#/components/schemas/JobLevels" }, "xml": { "wrapped": true } }, "jobFunctions": { "type": "array", "items": { "$ref": "#/components/schemas/JobFunctions" }, "xml": { "wrapped": true } }, "titles": { "type": "array", "items": { "type": "string", "xml": { "name": "title" } }, "xml": { "wrapped": true } } } }, "CompanyFetchResponseDTO": { "type": "object", "properties": { "companyId": { "type": "integer", "format": "int32" }, "companyName": { "type": "string" }, "description": { "type": "string" }, "companyType": { "type": "string" }, "companyStatus": { "type": "string" }, "tickers": { "type": "array", "items": { "$ref": "#/components/schemas/TickerDTO" }, "xml": { "wrapped": true } }, "classification": { "$ref": "#/components/schemas/ClassificationDTO" }, "address": { "$ref": "#/components/schemas/CompanyAddressDTO" }, "phone": { "type": "string" }, "revenue": { "type": "number", "format": "double", "description": "Annual revenue in millions." }, "revenueCurrency": { "type": "string" }, "employeeCount": { "type": "integer", "format": "int32" }, "sic": { "type": "string" }, "sicDescription": { "type": "string" }, "naics": { "type": "string" }, "naicsDescription": { "type": "string" }, "financialYearEnd": { "type": "string" }, "equifaxId": { "type": "string" }, "companyTaxId": { "type": "string" }, "fortuneRanking": { "type": "string" }, "britishSics": { "type": "array", "items": { "$ref": "#/components/schemas/BritishSicDTO" }, "xml": { "wrapped": true } }, "foundedIn": { "type": "string" }, "socialHandles": { "$ref": "#/components/schemas/SocialHandlesDTO" }, "diversity": { "$ref": "#/components/schemas/DiversityDTO" }, "siteTypes": { "type": "array", "items": { "type": "string", "xml": { "name": "siteType" } }, "xml": { "wrapped": true } }, "siteCount": { "type": "integer", "format": "int32" }, "siteLocationCount": { "type": "integer", "format": "int32" }, "businessStructure": { "type": "string" }, "currentCompanyId": { "type": "integer", "format": "int32" }, "websites": { "type": "array", "items": { "type": "string", "xml": { "name": "website" } }, "xml": { "wrapped": true } }, "companyCompetitorIds": { "type": "array", "items": { "type": "string" } }, "familyTree": { "$ref": "#/components/schemas/FamilyTreeResultDTO" }, "acquisitions": { "$ref": "#/components/schemas/AcquiredCompanyResultDTO" }, "techUsed": { "$ref": "#/components/schemas/CompanyTechUsedDTO" }, "companyLogos": { "type": "array", "items": { "type": "string", "xml": { "name": "companyLogo" } }, "xml": { "wrapped": true } }, "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDTO" }, "xml": { "wrapped": true } } }, "xml": { "name": "company" } }, "TickerDTO": { "type": "object", "properties": { "tickerName": { "type": "string" }, "exchange": { "type": "string" } } }, "ClassificationDTO": { "type": "object", "properties": { "primaryBusiness": { "$ref": "#/components/schemas/BusinessDTO" }, "secondaryBusinesses": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDTO" }, "xml": { "wrapped": true } } } }, "BusinessDTO": { "type": "object", "properties": { "industry": { "type": "string" }, "industryCode": { "type": "string" }, "subIndustry": { "type": "string" }, "subIndustryCode": { "type": "string" } } }, "BritishSicDTO": { "type": "object", "properties": { "britishSic": { "type": "string" }, "description": { "type": "string" } } }, "SocialHandlesDTO": { "type": "object", "properties": { "twitter": { "type": "string" }, "facebook": { "type": "string" }, "blog": { "type": "string" }, "linkedIn": { "type": "string" } } }, "DiversityDTO": { "type": "object", "properties": { "gender": { "type": "string" }, "ethnicity": { "type": "string" }, "certifications": { "$ref": "#/components/schemas/DiversityCertificationsDTO" } } }, "DiversityCertificationsDTO": { "type": "object", "properties": { "wbe": { "type": "boolean" }, "mbe": { "type": "boolean" }, "vbe": { "type": "boolean" }, "disabled": { "type": "boolean" }, "dbe": { "type": "boolean" }, "lgbt": { "type": "boolean" } } }, "FamilyTreeResultDTO": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/CompanyDTO" }, "children": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/FamilyTreeResultDTO" }, "xml": { "wrapped": true } } } }, "AcquiredCompanyResultDTO": { "type": "object", "properties": { "companies": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/CompanyDTO" }, "xml": { "wrapped": true } } } }, "CompanyTechUsedDTO": { "type": "object", "description": "Installed technology information grouped by category and subcategory.", "properties": { "categories": { "type": "array", "description": "Technology categories associated with the company.", "items": { "$ref": "#/components/schemas/TechUsedCategoryDTO" }, "xml": { "wrapped": true } } } }, "TechUsedCategoryDTO": { "type": "object", "description": "A technology category and its subcategories.", "properties": { "categoryId": { "type": "string", "description": "Demandbase identifier for the technology category.", "example": "61" }, "categoryName": { "type": "string", "description": "Display name of the technology category.", "example": "Analytics" }, "subCategories": { "type": "array", "description": "Technology subcategories within the category.", "items": { "$ref": "#/components/schemas/TechUsedSubCategoryDTO" }, "xml": { "wrapped": true } } } }, "TechUsedSubCategoryDTO": { "type": "object", "description": "A technology subcategory and its detected products.", "properties": { "subCategoryId": { "type": "string", "description": "Demandbase identifier for the technology subcategory.", "example": "5000076" }, "subCategoryName": { "type": "string", "description": "Display name of the technology subcategory.", "example": "Business Intelligence Software" }, "products": { "type": "array", "description": "Products detected for the company within the subcategory.", "items": { "$ref": "#/components/schemas/TechUsedProductDTO" }, "xml": { "wrapped": true } } } }, "TechUsedProductDTO": { "type": "object", "description": "A product detected for the company.", "properties": { "productId": { "type": "string", "description": "Demandbase identifier for the product.", "example": "DM01069" }, "productName": { "type": "string", "description": "Display name of the product.", "example": "Axio" } } }, "MatchRequestDTO": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/MatchRequest" } }, "fields": { "type": "array", "uniqueItems": true, "items": { "type": "string", "example": "[\"name\",\"city\"]" }, "example": [ "name", "city" ] }, "limitResults": { "type": "string", "example": "10" }, "matchBranch": { "type": "string", "example": "true" }, "minContactQualityScore": { "type": "string", "example": "A+" } }, "required": [ "requests" ] }, "MatchRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "Microsoft" }, "country": { "type": "string", "example": "United States" }, "state": { "type": "string", "example": "WA" }, "city": { "type": "string", "example": "Redmond" }, "street": { "type": "string", "example": "1 Microsoft Way" }, "zip": { "type": "string", "example": "90301" }, "websites": { "type": "array", "items": { "type": "string", "example": "[\"www.microsoft.com\"]" }, "example": [ "www.microsoft.com" ] }, "ticker": { "type": "string", "example": "MSFT" }, "phone": { "type": "string", "example": "+1 650 253 0000" }, "id": { "type": "string", "example": "id" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "title": { "type": "string", "example": "CEO" }, "fullName": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "isPhoneRequired": { "type": "boolean", "example": true }, "isEmailRequired": { "type": "boolean", "example": true }, "executiveLinkedInHandle": { "type": "string", "example": "john-doe" }, "contactMatching": { "type": "string", "example": "active" }, "contactStatus": { "type": "string", "example": "current" } }, "required": [ "id" ] }, "MatchResponseDTO": { "type": "object", "properties": { "matches": { "type": "array", "items": { "$ref": "#/components/schemas/MatchResponse" }, "xml": { "wrapped": true } } }, "xml": { "name": "MatchResults" } }, "MatchResponse": { "type": "object", "properties": { "id": { "type": "string" }, "companyMatches": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyMatchDTO" }, "xml": { "wrapped": true } }, "contactMatches": { "type": "array", "items": { "$ref": "#/components/schemas/ContactMatchDTO" }, "xml": { "wrapped": true } } } }, "CompanyMatchDTO": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/CompanyFetchResponseDTO" } } }, "ContactMatchDTO": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/ContactFetchResponseDTO" } } } } }, "security": [ { "bearerAuth": [] } ] } ````