Type = Technical Guides, Technical Tools, What's New,; Topic = Multienterprise Information Network Tower (MINT), Technical Documentation,;Persona = Solution Designer, TraceLink Administrator, User, Orchestration Architect, Solution Partner, Technology Partner,; Orchestration = Manufacturing, Logistics, Commerce, Transportation, Clinical Supply,; Function = IT, Quality, Procurement,

Organizational relationship canonical guidelines

The Organizational Relationships transaction is a master data message used to share structured information about organizational hierarchies, relationships, and identifiers between trading partners. It defines how companies, business units, and locations relate to one another—such as parent–subsidiary, company–location, or owner–partner relationships—and includes key data such as names, addresses, contacts, and identifiers like GLNs, DUNS numbers, or internal codes.

Canonical guidelines

Canonical Element						Type Definition	Description	IDoc mapping	X12 mapping	EDIFACT mapping
data						–	Object type/root element.	–	–	–
	controlFileHeader					–	Canonical control file header to store data for control segments of IDocs and TL XML transactions, and EDI envelopes for X12 and EDIFACT.	–	–	–
	canonicalOrganizationalRelationshipHeader					–	Payload for Organization Relationship.	–	Segment BHT	BGM
		processingFunctionTypeCode				string	Ocean Freight Invoice processing function code. Valid values include: `ORIGINAL` `CREATE` `CHANGE` `DELETE`	–	BHT02 = 00 (ORIGINAL) or 03 (DELETE) or 04 (CHANGE)	BGM030 = 2 (CREATE) or 3 (DELETE) or 4 (CHANGE) or 9 (ORIGINAL)
		hierarchyStructureType				string	Identifies the type of hierarchical structure applied in the transaction, defining how hierarchical levels are related to one another. Valid values include: `COMPANYOPERATINGUNIT` - Structure type is company and its operating unit. `SUPERGROUPSUBGROUPMEMBER` - Structure type is supergroup its subgroup and member	–	BHT01 = 0065 (COMPANYOPERATINGUNIT) Or 0057 (SUPERGROUPSUBGROUPMEMBER)	–
		transactionReferenceIdentifiers				array	Transaction references for deliveries at header level	–	Segment BHT	–
			b2bTransactionIdentifierType			string	Referenced document type. Valid values include `ORGANIZATIONALRELATIONSHIP` = Transaction identifier.	–	–	–
			b2bTransactionIdentifierValue			string	Reference identifier value for invoice and shipment.	–	BHT03 when b2bTransactionIdentifierType = ORGANIZATIONALRELATIONSHIP (required)	BGM020-010 when b2bTransactionIdentifierType = ORGANIZATIONALRELATIONSHIP (required)
			lineItemNumber			string	Line item number in transaction reference.	–	–	–
			transactionDate			string	Date transaction created.	–	BHT04 & BHT05 when b2bTransactionIdentifierType = ORGANIZATIONALRELATIONSHIP	DTM01-020 with DTM01-010 as 137 and DTM01-030 as 102 (Format: CCYYMMDD) when b2bTransactionIdentifierType = ORGANIZATIONALRELATIONSHIP
			epochTransactionDate			integer	Date transaction created in epoch integer date format.	–	–	–
		transactionReferenceInformation				array	Reference information for identifiers that are not related to transaction documents. This group would map to X12 segments L11 and N9 for information other than transaction documents.	–	REF segment	–
			transactionReferenceType			string	Transaction reference type for X12 segments REF and N9 for general reference data that is not a transaction document identifier.	–	REF01	RFF01-010
			transactionReferenceIdentifier			string	Transaction reference identifier value.	–	REF02	RFF01-020
			description			string	Identifier or description defined by qualifier code in transactionReferenceIdentifier (REF02).	–	–	–
			transactionReferenceDate			string	Transaction reference date and time/ if time available/ in date format YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS.nnnZ if time available.	–	–	–
			epochTransactionReferenceDate			integer	Transaction reference date and time in EPOCH date time format.	–	–	–
			mpcDates			array	Dates relevant for referenced document	–	–	RFF Loop/ DTM Loop
				dateType		string	Date type at header level for Application Advices in date format YYYYMMDD and time format (IDoc, X12) HHMMSS. Valid values include Dates relevant to reference information.	–	–	DTM010-010 = 137 (DOCUMENT)
				dateValue		string	Date defined by referenced date type in date format YYYY-MM-DD.	–	–	DTM010-020
				epochDateValue		integer	Date defined by referenced date type generated in epoch integer date format.	–	–	–
				dateTimePeriodFormat		string	Code specifying representation of date or time or format presented in date value. Valid values include: `CCYYMMDD` - Date format century year month day, 2 characters each `CCYYMMDDHHMM` - Date format century year month day hour minutes, 2 characters each	–	–	DTM010-030
				timeZone		string	Time zone for referenced dates.	–
		mpcDates				array	Document dates at header level.	–	Header DTM Loop	Header DTM Loop
			dateType			string	Date type.	–	DTM01	DTM01-010
			dateValue			string	Date defined by referenced date type.	–	DTM02 & DTM03	DTM01-020
			epochDateValue			integer	Date defined by referenced date type generated in epoch integer date format.	–	–	–
			dateTimePeriodFormat			string	Code specifying representation of date or time or format presented in date value, Valid values include: `CCYYMMDD` - Date format century year month day, 2 characters each `CCYYMMDDHHMM` - Date format century year month day hour minutes, 2 characters each	–	DTM05	DTM010-030
			timeZone			string	Time zone for referenced dates.	–	–	–
		partnerBusinessInformation				array	Party company identifiers and address information., like Message sender information.	–	N1 Loop	NAD Loop
			businessPartyInformation			–	Business Parties identifiers and address information.	–	N1	NAD
				partnerEntityType		string	Denotes type of the entity involved in this business transaction. Valid values include: `SENDER` - Message sender `RECEIVER` - Message receiver	–	N101 = FR (SENDER)	NAD01
				businessName		string	Business name for partner or location.	–	N102	NAD040-010
				additionalBusinessName		string	Additional Business name for partner or location.	–	N201	–
				companyLocationPartnerName		string	Additional Location of same Business partner.	–	–	–
				mpcCompanyLocationIdentifierList		array	Identifier list for business party.	–	–	–
					isIdentifierPresentInEvent	boolean	Is identifier present in event boolean.	–	–	–
					companyIdentifierType	string	Company identifier type for business partner.	–	N103 PartyEntityType = Carrier then 93 Shipper then 94	NAD020-030
					companyIdentifierValue	string	Company identifier value for business partner	–	N104	NAD020-010
					alternateCompanyLocationIdentifierValue	string	Alternate company location identifier value	–	–	–
				address		-	Party address information.	–	N3, N4,
					address1	string	Main street address.	–	N301	NAD050-010
					address2	string	Supplemental street address.	–	N302	NAD050-020
					city	string	City	–	N401	NAD060
					district	string	District	–	N/A	N/A
					state	string	State or region code.	–	N402	NAD070-010
					postalCode	string	Postal code	–	N403	NAD080
					country	string	Country code	–	N404	NAD090
					telephone	string	Telephone number	–	–	–
					fax	string	Fax number	–	–	–
					url	string	Website URL	–	–	–
					buildingNumber	string	Building number	–	–	–
					plantNumber	string	Plant number	–	–	–
					floorNumber	string	Floor number in building.	–	–	–
					lscAddressIdentifier	string	LSC address identifier.	–	–	–
					village	string	Village name	–	–	–
					houseNumber	string	House number	–	–	–
					township	string	Township	–	–	–
					premisesCode	string	Premises code	–	–	–
				companyLocationContactInformation		-	-	–	N1-PER	CTA
					contactType	string	Contact type. Valid values include: `INFORMATION` - Information contact `PRIMARY` - Primary contact `RESPONSIBLE` - Responsible person	–	PER01 = IC (INFORMATION)	CTA010 = IC (INFORMATION)
					contactName	string	Contact name.	–	PER02	CTA020-020
					contactTitle	string	Title of contact.	–	–	–
					contactPhone	string	Contact phone number.	–	PER04 where PER03 = "TE"	COM010-010 where COM010-020 = "TE"
					contactEmail	string	Contact email address.	–	PER06 where PER05 = "EM"	COM010-010 where COM010-020 = "EM"
				mpcAdditionalAddressInformation		–	Additional address information that is not included in addressTypeDefinition.	–	–	–
					externalERPUserName	string	External ERP system user name for user who generated message.	–	–	–
					organizationCode	string	Code for organization responsible for generating the message.	–	–	–
					organizationDescription	string	Description of the organization responsible for generating the message.	–	–	–
					groupCode	string	Code identifying group responsible for generating the message.	–	–	–
					language	string	Language key for message.	–	–	–
					languageCode	string	ISO language code for message.	–	–	–
					referenceIdentifier	string	Partner reference identifier.	–	–	–
					orderType	string	Order Type.	–	–	–
					address3	string	Additional address information that is not included in addressTypeDefinition.	–	–	–
					address4	string	Additional address information that is not included in addressTypeDefinition.	–	–	–
					postalArea	string	Postal Area.	–	–	–
					timeZone	string	Time zone for referenced dates.	–	–	–
					telephone	string	Telephone Number.	–	–	–
					emailAddress	string	Email Address	–	–	–
					vatRegistrationNumber	string	Vat Registration Number.	–	–	–
					taxExemptCode	string	Tax exempt Code	–	–	–
					locationType	string	Business Partner Location Type.	–	–	–
					locationIdentifier	string	Business Partner location Identifier.	–	–	–
					countrySubDivisionCode	string	Describes the country subdivision.	–	–	–
			transactionReferenceIdentifiers			array	Transaction references for deliveries at header level.	–	REF segment	Segment RFF
				b2bTransactionIdentifierType		string	Referenced document type.	–	REF01	RFF01-010
				b2bTransactionIdentifierValue		string	Reference identifier value for invoice and shipment.	–	REF02	RFF01-020
				lineItemNumber		string	Line item number in transaction reference. Line item level only.	–	–	–
				transactionDate		string	Date transaction created.	–	–	–
				epochTransactionDate		integer	Date transaction created in epoch integer date format.	–	–	–
			transactionReferenceInformation			array	Reference information for identifiers that are not related to transaction documents. This group would map to X12 segments REF and N9 and EDIFACT RFF for information other than transaction documents.	–	REF segment	Segment RFF
				transactionReferenceType		string	Transaction reference type for X12 segments REF and N9 and EDIFACT RFF for general reference data that is not a transaction document identifier.	–	REF01	RFF01-010
				transactionReferenceIdentifier		string	Transaction reference identifier value.	–	REF02	RFF01-020
				description		string	Identifier or description defined by qualifier.	–	–	–
				transactionReferenceDate		string	Transaction reference date and time/ if time available/ in date format YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS.nnnZ if time available.	–	–	–
				epochTransactionReferenceDate		integer	Transaction reference date and time in EPOCH date time format.	–	–	–
		freeTextNote				array	Free text, instructions, notes, descriptions and other free text elements.	–	–	Segment FTX
			textReferenceCode			string	Text reference or subject code.	–	–	FTX010
			textFunctionCode			string	Text function code.	–	–	FTX020
			language			string	Language key for message.	–	–	–
			languageCode			string	ISO language code for message.	–	–	–
			textFormatCode			string	Format code for free text.	–	–	–
			freeFormText			string	Free text array.	–	–	FTX040-010, FTX040-20, FTX040-030, FTX040-040
		customFields				array	Name value pairs for mapping pass through elements that will not be processed in TL system but may be passed outbound. Line item level.	–	–	–
			name			string	Name of mapped field.	–	–	–
			value			string	Value in named field.	–	–	–
	canonicalOrganizationalRelationshipLineItemDetails					array	Organizational relationship line items details.	–	HL Loop starts (Based on examples for each Hierarchical (H1) one entity(N1) is present.)	NAD Loop
		lineItemNumber				string	transaction set line number.	–
		hierarchicalLevel				array	Organizational hierarchical level for to denote its reporting level.	–	Segment HL instance	HYN Loop
			hierarchicalIdentifier			string	Hierarchical level counter. Increment each instance by 1 from the last.	–	HL01	HYN040-010
			hierarchicalParentIdentifier			string	Hierarchical identifier for the parent level of the current level. If there is no parent level this value would be the same as the current hierarchicalIdentifier.	–	HL02	HYN050
			hierarchicalLevelCode			string	Code identifying the hierarchical level of the hierarchical group in the organization Valid values include: `COMPANY` - Company or corporate level `BUSINESSENTITY` - Business entity level `SUPERGROUP` - Super group level `OPERATINGUNIT` - Operating unit, such as store, warehouse	–	HL03 = 35 (COMPANY) Or 24 (SUPERGROUP) Or BE (BUSINESSENTITY) 36 (OPERATINGUNIT)	HYN010
			hierarchicalChildCode			string	Code indicating if there are child data segments subordinate to the current HL level. Valid values: `ONE` - A child line item segment follows `ZERO` - No child line item segment follows	–	HL04 = 1 (ONE) Or ZERO (0)	If more then one HYN segment it has child, and parent child will be identified through HYN020
		organizationalEntityBusinessInformation				array	Represents a party participating in an organizational hierarchy, including identification, location, reference identifiers, effective dates, and relationship or maintenance attributes.	–	N1 Loop	NAD Loop
			organizationalEntityInformation				Business Parties identifiers and address information.	–	N1	–
				partnerEntityType		string	Denotes type of the entity involved in this business transaction, Valid values include: `SENDER` - Message sender `RECEIVER` - Message receiver	–	N101	NAD01
				businessName		string	Business name for partner or location.	–	N102	NAD040-010
				additionalBusinessName		string	Additional Business name for partner or location.	–	N201
				companyLocationPartnerName		string	Additional Location of same Business partner.	–	–	–
				mpcCompanyLocationIdentifierList		array	Identifier list for business party.	–	–	–
					isIdentifierPresentInEvent	boolean	Is identifier present in event boolean.	–	–	–
					companyIdentifierType	string	Company identifier type for business partner .	–	N103	NAD020-030 EDIFACT supported codes: `DUNS` - 16 `DEA` - 164 `HIN` - 21 `COMPANYID` - 91 `COMPANYSITEID` - 92
					companyIdentifierValue	string	Company identifier value for business partner.	–	N104	NAD020-010
					alternateCompanyLocationIdentifierValue	string	Alternate company location identifier value.	–	-	-
				address		-	Party address information.	–	N3, N4,	-
					address1	string	Main street address.	–	N301	NAD050-010
					address2	string	Supplemental street address.	–	N302	NAD050-020
					city	string	City	–	N401	NAD060
					district	string	District	–	–	–
					state	string	State or region code	–	N402	NAD070-010
					postalCode	string	Postal code	–	N403	NAD080
					country	string	Country code	–	N404	NAD090
					telephone	string	Telephone number	–	–	–
					fax	string	Fax number	–	–	–
					url	string	Website URL	–	–	–
					buildingNumber	string	Building number	–	–	–
					plantNumber	string	Plant number	–	–	–
					floorNumber	string	Floor number in building	–	–	–
					lscAddressIdentifier	string	LSC address identifier	–	–	–
					village	string	Village name	–	–	–
					houseNumber	string	House number	–	–	–
					township	string	Township	–	–	–
					premisesCode	string	Premises code	–	–	–
				companyLocationContactInformation		-	-	–	N1-PER	CTA
					contactType	string	Contact type. Valid values include: `INFORMATION` - Information contact `PRIMARY` - Primary contact `RESPONSIBLE` - Responsible person	–	PER01 = IC (INFORMATION)	CTA010 = IC (INFORMATION)
					contactName	string	Contact name.	–	PER02	CTA020-020
					contactTitle	string	Title of contact.	–	–	–
					contactPhone	string	Contact phone number.	–	PER04 where PER03 = "TE"	COM010-010 where COM010-020 = "TE"
					contactEmail	string	Contact email address.	–	PER06 where PER05 = "EM"	COM010-010 where COM010-020 = "EM"
				mpcAdditionalAddressInformation		-	Additional address information that is not included in addressTypeDefinition.	–	–	–
					externalERPUserName	string	External ERP system user name for user who generated message.	–	–	–
					organizationCode	string	Code for organization responsible for generating the message.	–	–	–
					organizationDescription	string	Description of the organization responsible for generating the message.	–	–	–
					groupCode	string	Code identifying group responsible for generating the message.	–	–	–
					language	string	Language key for message.	–	–	–
					languageCode	string	ISO language code for message.	–	–	–
					referenceIdentifier	string	Partner reference identifier.	–	–	–
					orderType	string	Order Type.	–	–	–
					address3	string	Additional address information that is not included in addressTypeDefinition.	–	N202	–
					address4	string	Additional address information that is not included in addressTypeDefinition.	–	–	–
					postalArea	string	Postal Area.	–	–	–
					timeZone	string	Time zone for referenced dates.	–	–	–
					telephone	string	Telephone Number.	–	–	–
					emailAddress	string	Email Address	–	–	–
					vatRegistrationNumber	string	Vat Registration Number.	–	–	–
					taxExemptCode	string	Tax exempt Code	–	–	–
					locationType	string	Business Partner Location Type.	–	–	–
					locationIdentifier	string	Business Partner location Identifier.	–	–	–
					countrySubDivisionCode	string	Describes the country subdivision.	–	–	–
			entityAction			-	Indicates type of action to be taken or taken on the organization data.	–	ASI	–
				statusActionCode		string	Identifies the business action to be performed or that has been performed on an entity. Valid values include: `CHANGE` - Update the record in master data. `ADD` - Adding `DELETE` - Deleting the record	–	ASI01= 1 (ADD) Or 2 (CHANGE) Or 3 (DELETE)	HYN‑030
				maintenanceScopeType		string	Specifies the type or scope of maintenance applied when performing the action, such as full replacement or selective update of entity data. Valid values: `CHANGE` - Existing item record is being updated `DELETE` - This item should no longer exist / be used `ADD` - This is a brand-new item create it	–	ASI02 = 001 (CHANGE) Or 002 (DELETE) Or 003 (ADD)	–
				transactionStatusReasonCode		string	Indicates the reason or justification for the action or status change of the entity.	–	ASI03	–
			transactionReferenceIdentifiers			array	Transaction references for deliveries at header level.	–	REF segment	Segment RFF
				b2bTransactionIdentifierType		string	Referenced document type.	–	REF01	RFF01-010
				b2bTransactionIdentifierValue		string	Reference identifier value for invoice and shipment.	–	REF02	RFF01-020
				lineItemNumber		string	Line item number in transaction reference. Line item level only.	–	–	–
				transactionDate		string	Date transaction created.	–	–	–
				epochTransactionDate		integer	Date transaction created in epoch integer date format.	–	–	–
			transactionReferenceInformation			array	Reference information for identifiers that are not related to transaction documents. This group would map to X12 segments REF and N9 and EDIFACT RFF for information other than transaction documents.	–	REF segment	Segment RFF
				transactionReferenceType		string	Transaction reference type for X12 segments REF and N9 and EDIFACT RFF for general reference data that is not a transaction document identifier. Valid values include: `DUNSWITHSUFFIX` - DUNS number with four character suffix `DISTRIBUIONCENTER` - Distribution Center identifier `STORENUMBER` - Store number	–	REF01 = DNS (DUNSWITHSUFFIX) Or AEM (DISTRIBUIONCENTER) Or ST (STORENUMBER)	RFF01-010
				transactionReferenceIdentifier		string	Transaction reference identifier value	–	REF02	RFF01-020
				description		string	Identifier or description defined by qualifier code in transactionReferenceIdentifier (REF02).	–	REF03	–
				transactionReferenceDate		string	Transaction reference date and time/ if time available/ in date format YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS.nnnZ if time available.	–	–	–
				epochTransactionReferenceDate		integer	Transaction reference date and time in EPOCH date time format.	–	–	–
				mpcDates		array	Dates relevant for referenced document	–	–	RFF Loop/ DTM Loop
					dateType	string	Date type at header level for Application Advices in date format YYYYMMDD and time format (IDoc, X12) HHMMSS. Valid values include: - Dates relevant to reference information.	–	–	DTM010-010
					dateValue	string	Date defined by referenced date type in date format YYYY-MM-DD.	–	–	DTM010-020
					epochDateValue	integer	Date defined by referenced date type generated in epoch integer date format.	–	–	–
					dateTimePeriodFormat	string	Code specifying representation of date or time or format presented in date value, Valid values include: `CCYYMMDD` - Date format century year month day, 2 characters each `CCYYMMDDHHMM` - Date format century year month day hour minutes, 2 characters each	–	–	DTM010-030
					timeZone	string	Time zone for referenced dates	–	–	–
			mpcDates			array	Dates relevant for party address or location or other information effective date.	–	DTM	NAD Loop / DTM Loop
				dateType		string	Date type at header level for Application Advices in date format YYYYMMDD and time format (IDoc, X12) HHMMSS. Valid values include `EFFECTIVE` - Effective date.	–	DTM01 = 007 (EFFECTIVE)	DTM010-010 = 7 (EFFECTIVE)
				dateValue		string	Date defined by referenced date type in date format YYYY-MM-DD.	–	DTM02	DTM010-020
				epochDateValue		integer	Date defined by referenced date type generated in epoch integer date format.	–	–	–
				dateTimePeriodFormat		string	Code specifying representation of date or time or format presented in date value, Valid values include: `CCYYMMDD` - Date format century year month day, 2 characters each `CCYYMMDDHHMM` - Date format century year month day hour minutes, 2 characters each	–	DTM05 = D8 (CCYYMMDD)	DTM010-030
				timeZone		string	Time zone for referenced dates.	–	–	–
		freeTextNote				array	Free text, instructions, notes, descriptions and other free text elements.	–	–	Segment FTX
			textReferenceCode			string	Text reference or subject code.	–	–	FTX010
			textFunctionCode			string	Text function code.	–	–	FTX020
			language			string	Language key for message.	–	–	–
			languageCode			string	ISO language code for message.	–	–	–
			textFormatCode			string	Format code for free text	–	–	–
			freeFormText			string	Free text array.	–	–	FTX040-010, FTX040-20, FTX040-030, FTX040-040
	customFields					array	Name value pairs for mapping pass through elements that will not be processed in TL system but may be passed outbound. Line item level.	–	–	–
		name				string	Name of mapped field.	–	–	–
		value				string	Value in named field.	–	–	–

Tag end