@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Companies
@base https://api.hubapi.com
@version v3
@auth OAuth2 | ApiKey private-app-legacy in header | ApiKey private-app in header
@endpoints 12
@toc crm(12)

@endpoint GET /crm/v3/objects/companies
@desc Retrieve companies
@optional {after: str # The paging cursor token of the last successfully read resource will be returned as the `paging.next.after` JSON property of a paged response containing more results., archived: bool=false # Whether to return only results that have been archived., associations: [str] # A comma separated list of object types to retrieve associated IDs for. If any of the specified associations do not exist, they will be ignored., limit: int(int32)=10 # The maximum number of results to display per page., properties: [str] # A comma separated list of the properties to be returned in the response. If any of the specified properties are not present on the requested object(s), they will be ignored., propertiesWithHistory: [str] # A comma separated list of the properties to be returned along with their history of previous values. If any of the specified properties are not present on the requested object(s), they will be ignored. Usage of this parameter will reduce the maximum number of objects that can be read by a single request.}
@returns(200) {paging: map{next: map{after: str, link: str}}, results: [map]} # successful operation

@endpoint POST /crm/v3/objects/companies
@desc Create a company
@required {associations: [map{to!: map, types!: [map]}], properties: map # The company property values to set.}
@returns(201) {archived: bool, archivedAt: str(date-time), createdAt: str(date-time), id: str, objectWriteTraceId: str, properties: map, propertiesWithHistory: map, updatedAt: str(date-time), url: str} # successful operation

@endpoint POST /crm/v3/objects/companies/batch/archive
@desc Archive a batch of companies
@required {inputs: [map{id!: str}]}
@returns(204) No content

@endpoint POST /crm/v3/objects/companies/batch/create
@desc Create a batch of companies
@required {inputs: [map{associations!: [map], objectWriteTraceId: str, properties!: map}]}
@returns(201) {completedAt: str(date-time), links: map, requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # successful operation
@returns(207) {completedAt: str(date-time), errors: [map], links: map, numErrors: int(int32), requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # multiple statuses

@endpoint POST /crm/v3/objects/companies/batch/read
@desc Retrieve a batch of companies
@required {inputs: [map{id!: str}], properties: [str] # Key-value pairs for setting properties for the new object., propertiesWithHistory: [str] # Key-value pairs for setting properties for the new object and their histories.}
@optional {archived: bool=false # Whether to return only results that have been archived., idProperty: str # When using a custom unique value property to retrieve records, the name of the property. Do not include this parameter if retrieving by record ID.}
@returns(200) {completedAt: str(date-time), links: map, requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # successful operation
@returns(207) {completedAt: str(date-time), errors: [map], links: map, numErrors: int(int32), requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # multiple statuses

@endpoint POST /crm/v3/objects/companies/batch/update
@desc Update a batch of companies
@required {inputs: [map{id!: str, idProperty: str, objectWriteTraceId: str, properties!: map}]}
@returns(200) {completedAt: str(date-time), links: map, requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # successful operation
@returns(207) {completedAt: str(date-time), errors: [map], links: map, numErrors: int(int32), requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # multiple statuses

@endpoint POST /crm/v3/objects/companies/batch/upsert
@desc Create or update a batch of companies by unique property values
@required {inputs: [map{id!: str, idProperty: str, objectWriteTraceId: str, properties!: map}]}
@returns(200) {completedAt: str(date-time), links: map, requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # successful operation
@returns(207) {completedAt: str(date-time), errors: [map], links: map, numErrors: int(int32), requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # multiple statuses

@endpoint POST /crm/v3/objects/companies/merge
@desc Merge two companies
@required {objectIdToMerge: str # The ID of the company to merge into the primary., primaryObjectId: str # The ID of the primary company, which the other will merge into.}
@returns(200) {archived: bool, archivedAt: str(date-time), createdAt: str(date-time), id: str, objectWriteTraceId: str, properties: map, propertiesWithHistory: map, updatedAt: str(date-time), url: str} # successful operation

@endpoint POST /crm/v3/objects/companies/search
@desc Search for companies
@required {after: str # A paging cursor token for retrieving subsequent pages., filterGroups: [map{filters!: [map]}] # Up to 6 groups of filters defining additional query criteria., limit: int(int32) # The maximum results to return, up to 200 objects., properties: [str] # A list of property names to include in the response., sorts: [str] # Specifies sorting order based on object properties.}
@optional {query: str # The search query string, up to 3000 characters.}
@returns(200) {paging: map{next: map{after: str, link: str}, prev: map{before: str, link: str}}, results: [map], total: int(int32)} # successful operation

@endpoint GET /crm/v3/objects/companies/{companyId}
@desc Retrieve a company
@required {companyId: str}
@optional {archived: bool=false # Whether to return only results that have been archived., associations: [str] # A comma separated list of object types to retrieve associated IDs for. If any of the specified associations do not exist, they will be ignored., idProperty: str # The name of a property whose values are unique for this object type, properties: [str] # A comma separated list of the properties to be returned in the response. If any of the specified properties are not present on the requested object(s), they will be ignored., propertiesWithHistory: [str] # A comma separated list of the properties to be returned along with their history of previous values. If any of the specified properties are not present on the requested object(s), they will be ignored.}
@returns(200) {archived: bool, archivedAt: str(date-time), associations: map, createdAt: str(date-time), id: str, objectWriteTraceId: str, properties: map, propertiesWithHistory: map, updatedAt: str(date-time), url: str} # successful operation

@endpoint DELETE /crm/v3/objects/companies/{companyId}
@desc Archive a company
@required {companyId: str}
@returns(204) No content

@endpoint PATCH /crm/v3/objects/companies/{companyId}
@desc Update a company
@required {companyId: str, properties: map # The company property values to set.}
@optional {idProperty: str # The name of a property whose values are unique for this object type}
@returns(200) {archived: bool, archivedAt: str(date-time), createdAt: str(date-time), id: str, objectWriteTraceId: str, properties: map, propertiesWithHistory: map, updatedAt: str(date-time), url: str} # successful operation

@end