{"openapi":"3.0.1","info":{"title":"Demographics API","description":"Enable insightful, impactful, and equitable giving decisions with a dynamic snapshot of Demographics data.","license":{"name":"Candid API License Agreement"},"version":"1.0"},"servers":[{"url":"https://api.candid.org/demographics","description":"Production Server"}],"paths":{"/v1/{ein}":{"get":{"tags":["v1"],"description":"Use an EIN in the path parameter to retrieve data on a nonprofit's Demographics data.","summary":"/demographics/v1","operationId":"demographics_v1","parameters":[{"name":"ein","in":"path","description":"Employer Identification Number","required":true,"schema":{"type":"string","example":"13-1837418"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotAcceptable"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequests"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}}},"components":{"securitySchemes":{"apiKeyHeader":{"type":"apiKey","name":"Subscription-Key","in":"header"},"apiKeyQuery":{"type":"apiKey","name":"Subscription-Key","in":"query"}},"schemas":{"APIResponse":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP response status code","example":200},"message":{"type":"string","description":"Diagnostic message for response status","example":"Request was processed successfully!"},"took":{"type":"integer","description":"Time taken for request to process in milliseconds","example":24},"errors":{"type":"array","items":{"type":"string"},"description":"List of errors encountered"},"data":{"$ref":"#/components/schemas/Data"}},"additionalProperties":false},"Categories":{"type":"object","properties":{"category_id":{"type":"integer","description":"Category Id","example":1},"category":{"type":"string","nullable":true,"example":"Race & Ethnicity"},"board_members_not_collected":{"type":"boolean","description":"Presence of board member data collected in category","nullable":true,"example":false},"staff_not_collected":{"type":"boolean","description":"Presence of staff data collected in category","nullable":true,"example":false},"senior_staff_not_collected":{"type":"boolean","description":"Presence of senior staff data collected in category","nullable":true,"example":false},"subcategories":{"type":"array","items":{"$ref":"#/components/schemas/SubCategories"},"description":"Subcategory descriptions","nullable":true}},"additionalProperties":false,"description":"Demographic totals for staff"},"Data":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/Summary"},"demographics":{"$ref":"#/components/schemas/Demographics"}}},"Demographics":{"type":"object","properties":{"staff_level_totals":{"$ref":"#/components/schemas/StaffLevelTotals"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Categories"},"description":"Demographic totals for staff","nullable":true}},"additionalProperties":false},"StaffLevelTotals":{"type":"object","properties":{"total_board_members":{"type":"string","description":"Total number of board members","nullable":true,"example":"18"},"total_staff":{"type":"string","description":"Total number of staff","nullable":true,"example":"195"},"total_senior_staff":{"type":"string","description":"Total number of senior staff","nullable":true,"example":"8"}},"additionalProperties":false,"description":"Demographic totals for staff"},"SubCategories":{"type":"object","properties":{"subcategory_id":{"type":"integer","description":"Subcategory Id","example":1},"subcategory":{"type":"string","description":"Subcategory description","nullable":true,"example":"Asian/Asian American"},"board_members":{"type":"integer","description":"Board members in demographic group","nullable":true,"example":2},"staff":{"type":"integer","description":"Staff members in demographic group","nullable":true,"example":26},"senior_staff":{"type":"integer","description":"Senior staff members in demographic group","nullable":true,"example":4},"reported_by_ceo":{"type":"boolean","description":"Whether or not reported by CEO","nullable":true,"example":false},"reported_by_coceo":{"type":"boolean","description":"Whether or not reported by co CEO","nullable":true,"example":null}},"additionalProperties":false,"description":"Subcategory descriptions"},"Summary":{"type":"object","properties":{"organization_name":{"type":"string","description":"Organization name","nullable":true,"example":"Candid"},"candid_entity_id":{"type":"string","description":"Candid internal organization ID, can be a different value than organization_id","example":"6908122"},"ein":{"type":"string","description":"Employee identification number","nullable":true,"example":"13-1837418"},"city":{"type":"string","description":"Organization address city","nullable":true,"example":"New York City"},"state":{"type":"string","description":"Organization address state","nullable":true,"example":"NY"},"demographics_status":{"type":"string","description":"Description of demographics status that can be displayed to a funder or donor","nullable":true,"example":"This organization has provided Candid demographics data on 06/23/2023"},"demographics_status_nonprofit":{"type":"string","description":"Description of demographics status that can be displayed to a nonprofit","nullable":true,"example":"Your organization has provided Candid demographics data on 06/23/2023"},"date_last_modified":{"type":"string","description":"Last modified date of organization","nullable":true,"example":"01/02/2023"}},"additionalProperties":false},"BadRequest":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":400},"message":{"type":"string","example":"The request cannot be fulfilled due to bad syntax."},"took":{"type":"integer","description":"Time taken for request to process","example":24},"errors":{"type":"array","description":"List of errors encountered","items":{"type":"string"}}}},"Unauthorized":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":401},"message":{"type":"string","example":"Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."}}},"Forbidden":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":403},"message":{"type":"string","example":"Forbidden, we found insufficient permissions to grant access to the resources. Please check the detailed message of the response."}}},"NotFound":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP response status code.","example":404},"message":{"type":"string","example":"Request was processed successfully but we could not find the resource ein"},"took":{"type":"integer","description":"Time taken for request to process","example":24},"errors":{"type":"array","description":"List of errors encountered","items":{"type":"string"}}}},"NotAcceptable":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":406},"message":{"type":"string","example":"The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request."}}},"TooManyRequests":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":429},"message":{"type":"string","example":"Rate limit is exceeded. Try again later."}}},"InternalServerError":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":500},"message":{"type":"string","example":"Oh no!, this is bad, something went wrong... please contact API support!"}}}}},"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]}],"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}